UNIX® System V 

DOCUMENTOR'S WORKBENCH 

User's Guide 



AT&T 



UNIX® System V 

DOCUMENTOR'S WORKBENCH 

User's Guide 




Prentice Hall, Englewood Cliffs, New Jersey 07632 



© 1989, 1986 by AT&T 



All rights reserved. No part of this book may be 
reproduced, in any form or by any means, 
without permission in writing fix)m the publisher. 



Printed in the United States of America 
10 987654321 



ISBN Q-13-TM3S^fi-D 



Prentice-Hall International (UK) Limited, London 
Prentice-Hall of Australia Pty. Limited, Sydney 
Prentice-Hall Canada Inc., Toronto 
Prentice-Hall Hispanoamericana, S.A,, Mexico 
Prentice-Hall of India Private Limited, New Delhi 
Prentice-Hall of Japan, Inc., Tokyo 
Simon & Schuster Asia Pte. Ltd., Singapore 
Editora Prentice-Hall do Brasil, Ltda., Rio de Janeiro 



Table of Contents 



Product Overview 
User's Guide 

Handbook for New Users 



V 



310-006 
Issue 1 



UNIX"" System V 

DOCUMENTER'S WORKBENCH 
Software Release 2.0 

Product Overview 



©1986 AT&T 

All Rights Reserved 

Printed in USA 

NOTICE 

The information in this document is subject to change without notice. AT&T 
assumes no responsibility for any errors that may appear in this document. 

9700 is a trademarl^ of Xerox. 

APS-5 is a trademark of Autologic. 

DEC is a trademarl< of Digital Equipment. 

DOCUMENTER'S WORKBENCH is a trademarl< of AT&T 

IMPRINT is a trademark of IMAGEN. 

PDP is a trademark of Digital Equipment. 

TEKTRONIX is a trademark of Tektronix. 

Teletype is a registered trademark of AT&T 

UNIX is a trademark of AT&T 

VAX is a trademark of Digital Equipment. 



L-243660-17 



Table of Contents 



Introduction i 

Description 2 

Programs 3 

Obsolete Programs 5 

Documentation 7 

Overview of Technical Information 9 

Supported Hardware 9 

Specifications for the 3B2 Computer 10 

Terminal Dependencies 10 

Software Dependencies 10 



TABLE OF CONTENTS iii 



Introduction 

The DOCUMENTER'S WORKBENCH Software is a set of computer pro- 
grams developed at AT&T Bell Laboratories to run under the UNIX operating 
system. These programs help you format any type of document. The 
DOCUMENTER'S WORKBENCH Software supports a range of output devices 
from typewriter-like printers to phototypesetting equipment. 
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Description 



The DOCUMENTER'S WORKBENCH Software is a powerful and sophisti- 
cated set of text formatting tools that helps you produce a wide variety of 
documents, including letters, research papers, memoranda, reports, and 
books. You can use the DOCUMENTER'S WORKBENCH Software to create 
documents that contain tables , mathematical equations, line drawings, and 
plots of data. 

With the DOCUMENTER'S WORKBENCH Software you can dramatically 
diminish the time you need to plan and prepare the following features of 
your document. 

■ margins 

■ titles 

■ lists and displays 

■ footnotes 

■ page headers and footers 

■ page numbering 

■ table of contents 

■ glossary 

■ index 

Anyone can run the DOCUMENTER'S WORKBENCH programs— a clerk, a 
secretary, the writer or editor— you need only a basic familiarity with the 
UNIX operating system. Using any UNIX system text editor, you type in 
your text and intersperse formatting instructions (such as .P for paragraph), 
that state precisely how you want your document to look when it is printed. 
Then you choose the appropriate preprocessors and formatter to process 
your file for printing. 
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Programs 



The DOCUMENTER'S WORKBENCH programs can be grouped into the 
following general categories: 

Formatters nroff and troff are text-formatting programming 

languages for typewriter-like printers and photo- 
typesetters, respectively. These "super word proces- 
sors" are at the heart of the DOCUMENTER'S WORK- 
BENCH Software. The macro packages and prepro- 
cessors (see below) create instructions that the for- 
matters use to produce a formatted document. 

Macro There are four macro packages available with the 

DOCUMENTER'S WORKBENCH Software: mm, mv, 
man, and mptx. The mm, or Memorandum Macros, 
package allows you to produce memoranda and 
letters easily. The mv package allows you to make 
high quality typeset transparencies in a variety of 
sizes. The man macro package allows you to format 
UNIX system manual pages, and mptx allows you to 
format a permuted index. 

Preprocessors Four preprocessors are included with the 

DOCUMENTER'S WORKBENCH Software: tbl, eqn, 
pic, and grap. tbl helps you make tables: large or 
small, simple or complex, eqn enables you to 
present mathematical notation easily, pic enables 
you to draw a wide variety of forms and line pic- 
tures, and grap, a "language" for describing plots of 
data, automatically scales and labels axes. Preproces- 
sors are used in conjunction with the text formatters 
nroff or troff to produce your final formatted file. 

Programs to Create an Index 

subj scans your document to collect a list of key- 
words, ndx creates an index from the keyword list 
subj makes. 

Programs for Comparing and Checking Documents 

checkmm checks input files and tells you if you 
have made any syntax errors in the DOCUMENTER'S 
WORKBENCH formatting instructions, diffmk 
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Programs 



compares two versions of a document and produces 
a third version that highlights the differences 
between the two original files, macref produces a 
cross-reference of the requests, macros, number 
registers, and strings that you use in a file. It is 
helpful for those who want to develop new sets of 
macros. 

Postprocessors daps translates troff output for an Autologic APS-5 

phototypesetter. dilO translates output from trojff 
for an Imagen IMPRINT-10 laser printer, tc turns 
troff output into code that a TEKTRONIX 4015 
typesetter can use. 
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Obsolete Programs 



Several programs that were included with Release 1.0 of the 
DOCUMENTER'S WORKBENCH Software are not in Release 2.0. 



checkcw 



checkeq 



dx9700 



mmlint 



non-btLsh 



ocw 



osdd 



is used with ocw, the preprocessor for otroff . It checks 
whether left and right delimiters and .CW/.CN pairs are 
properly balanced. Because otroff is not distributed with 
DOCUMENTER'S WORKBENCH Software 2.0, there is no 
longer a need for checkcw. 

is used with eqn. checkeq is not included in 
DOCUMENTER'S WORKBENCH Release 2.0 because the com- 
mand checkmm provides more extensive checking of proper 
equation formatting. 

prepares troff documents for the Xerox 9700 printer. The 
Xerox 9700 is no longer a supported device, and so the com- 
mand is not distributed with DOCUMENTER'S WORKBENCH 
Release 2.0. 

is a sroff/mm— nroff /mm document compatibility checker. 
Because sroff /mm is not distributed with DOCUMENTER'S 
WORKBENCH Release 2.0, there is no longer a need for 
mmlint. 

reinstalls mm macros without AT&T Bell Laboratories 
specific features. This command is not included with 
DOCUMENTER'S WORKBENCH Release 2.0 because AT&T Bell 
Laboratories specific strings have been moved to an external 
file called /usr/pub/strings.mm. The system administrator 
can edit this external file to meet local needs. 

is a preprocessor for otroff. Because otroff is not distributed 
with DOCUMENTER'S WORKBENCH Release 2.0, there is no 
longer a need for ocw. 

The osdd adapter macro package is a tool used with the mm 
macro package to prepare Operations Systems Deliverable 
Documentation. The command is not distributed with 
DOCUMENTER'S WORKBENCH Release 2.0. 
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otc is a postprocessor for otroff . Because otroff is not distri- 

buted with DOCUMENTER'S WORKBENCH Release 2.0, there 
is no longer a need for otc. 

otroff The otroff text formatter is an early version of troff that for- 

mats text for only one device, the C/A/T phototypesetter. 
otroff is not distributed with DOCUMENTER'S WORKBENCH 
Release 2.0. 

sroff sroff formats text for printing on typewriter-like devices and 

line printers, including the Xerox 9700 printer. The Xerox 
9700 is no longer a supported device; therefore, sroff is not 
distributed with DOCUMENTER'S WORKBENCH Release 2.0. 

X9700 prepares nroff documents for the Xerox 9700 printer. The 

Xerox 9700 is no longer a supported device; therefore, the 
command x9700 is not distributed with DOCUMENTER'S 
WORKBENCH Release 2.0. 
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Documentation 



The following documents are available for Release 2.0 of the 
DOCUMENTER'S WORKBENCH Software system: 

■ UNIX System V DOCUMENTER'S WORKBENCH Software User's 
Guide (Select Code 310-004): The User's Guide contains three 
sections: 1) the "Sampler/' which shows files before and after 
formatting, 2) a preface, and 3) tutorials. The first two sec- 
tions familiarize the novice with the software in general, and 
the tutorials cover its use in detail. 

■ UNIX System V DOCUMENTER'S WORKBENCH Software Technical 
Discussion and Reference Manual (Select Code 310-005): Organ- 
ized to suit the more experienced user, this technical explana- 
tion of the software is presented according to patterns of cus- 
tomary use. The components of the software are discussed in 
detail, and manual pages are also provided. 

■ UNIX System V DOCUMENTER'S WORKBENCH Software Handbook 
(Select Code 310-008): The Handbook is a memory jogger for 
accomplished users who want a more technical understanding 
of the software. 

■ UNIX System V DOCUMENTER'S WORKBENCH Software Handbook 
for New Users (Select Code 310-009): This handbook is aimed 
at new users. It is task-oriented, and it incorporates aspects of 
the *'Sampler" from the User's Guide, 

■ UNIX System V DOCUMENTER'S WORKBENCH Software Product 
Overview (Select Code 310-006): This document provides a 
summary of the software and its features, a list of available 
documents, and a brief technical description for those who 
might be asked to evaluate the software. 

■ UNIX System V DOCUMENTER'S WORKBENCH Software Release 
Notes (Select Code 310-007): The Release Notes, written for 
system administrators, includes the software installation pro- 
cedures for all processors that support the DOCUMENTER'S 
WORKBENCH Software. In addition, it gives transition infor- 
mation for owners of earlier product releases. 
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You may get copies of the documents in this list from AT&T. When 
placing orders, refer to the Select Code for the document that you want (for 
example 310-004 for the User's Guide), 

write to: AT&T Customer Information Center 

P.O.Box 19901 
Indianapolis, Indiana 46219 

or call: 1-800-432-6600 within the continental United States 

To order the DOCUMENTER'S WORKBENCH Software Release 2.0 call 
1-800-828-UNIX for the source product 

1-800-247-1212 for the binary product 
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Supported Hardware 

The following list identifies the hardware on which DOCUMENTER'S 
WORKBENCH Release 2.0 is supported for UNIX System V Release 2.0 as of 
April 1985: 

■ AT&T 352/300,400 Computers 

■ AT&T 3B5 Computer 

■ AT&T 3B20S/A Computers 

■ VAX 750 

The UNIX operating system and components of the DOCUMENTER'S 
WORKBENCH Software have been run on various other computers, includ- 
ing DEC PDP-11/45, PDP-11/70, and VAX-1 1/780 mini-computers. 

Specifications for the 3B20 Computer and tlie VAX 

For the AT&T 3B20 Computer and the DEC VAX-1 1/780 and VAX-1 1/750 
computers, the source code for the DOCUMENTER'S WORKBENCH Software 
Release 2.0 is distributed on a single magnetic tape containing two files in 
epic format, written at 1600 bpi. Only a system administrator with root 
privileges may access this tape. Installing the object code of DOCUMENTER'S 
WORKBENCH Software Release 2.0 also requires root userid privileges. The 
Release Notes (310-007) presents complete installation instructions. 



Specifications for the 3B5 Computer 

For the 3B5 Computer, source code is distributed on either a Lark II disk 
cartridge or a nine-track magnetic tape, and contains two files in epic for- 
mat. (The binary version of the DOCUMENTER'S WORKBENCH is only avail- 
able on nine-track magnetic tape.) Again, it is written at 1600 bpi, and root 
userid privileges are required. The Release Notes (310-007) presents com- 
plete installation instructions. 
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Specifications for the 3B2 Computer 

Installing the DOCUMENTER'S WORKBENCH Software on the 3B2 Com- 
puter requires four floppy disks. Each floppy disk contains "install" and 
"uninstall" scripts for the installation and removal of the files contained on 
it. The required disk space for this product is 5500 blocks in the /usr file 
system. 

The first floppy disk contains all files that you need to use troff, grap, 
mmt, mvt, pic, eqn and tc plus a driver (for the Autologic APS-5 typesetter) 
and the font tables for this driver. The files on this first disk require 1100 
blocks (512 bytes/block) of free space in the /usr file system. 

The second floppy disk contains all the files you need to use nroff, 
neqn, mm, and man. The files on this disk require 750 blocks of free space 
in the /usr file system. 

The third floppy disk contains files used by both nroff and troff. This 
disk requires 1300 blocks of free space in the /usr file system. 

The fourth floppy disk contains the driver, font tables and raster tables 
for the Imagen IMPRINT-10 laser printer. The files on this disk require 
2350 blocks of free space in the /usr file system. 

You can find a detailed list of the files on each floppy together with 
complete instructions for installation in the Release Notes, 



Terminal Dependencies 

You can display text processed by nroff, tbl, neqn and mm on a 
typewriter-like printer or on a terminal without graphics capabilities. Text 
processed by troff, the mv macro package, eqn, pic, and grap must be sent 
to a terminal or a printer that supports typesetting (for example, a Teletype 
5620 terminal). 



Software Dependencies 

AT&T supports the DOCUMENTER'S WORKBENCH Software Release 2.0 
only on UNIX System V Release 2.0 and subsequent releases. AT&T does 
not support DOCUMENTER'S WORKBENCH Software Release 2.0 on any other 
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version of the UNIX system. All the software that the DOCUMENTER'S 
WORKBENCH Software needs for installation and execution is part of UNIX 
System V Release 2.0 and subsequent releases. 

On AT&T 3B2 Computers, the following utilities packages must be 
installed before the DOCUMENTER'S WORKBENCH Software can be installed: 

Directory and File Management Utilities Package 

Terminal Filter Utilities Package (must be purchased separately) 

The installation script checks that these packages are installed on your 
3B2 Computer and will prevent you from installing the DOCUMENTER'S 
WORKBENCH Software if they are not installed. 
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Introduction 



The DOCUMENTER'S WORKBENCH Software provides a family of pro- 
grams for typesetting materials containing equations, tables, and diagrams, 
as well as standard text. The base upon which these interrelated programs 
rest is a text formatter called troff, a generic term for nroff/troff, developed 
by Joseph P, Ossanna around 1973. By itself, troff, with its many requests 
and escape sequences, provides a highly detailed level of text processing, 
performing few high-level formatting operations beyond line filling and 
justification. It accepts input from other, more specialized programs. In 
particular, page layout is controlled by the mm macro package, so-called 
because troff is a macro processor. 

Several DOCUMENTER'S WORKBENCH Software programs deal with 
specific areas of document preparation, eqn, for example, is a language for 
typesetting mathematical expressions. It acts as a preprocessor for troff. 
That is, the high-level instructions you give eqn are compiled into the 
lower-level troff code that will actually plot the desired mathematical nota- 
tion. The other DOCUMENTER'S WORKBENCH Software preprocessors are 
eqn, tbl, pic, and grap. 

grap, actually, is a "pre-preprocessor." This language, which you use to 
make graphs of numerical data, accepts English-oriented input and directs 
its output to pic, which in turn feeds troff. 

Finally, troff's output, however produced, can be directed to any of a 
large number of devices, ranging from conventional typesetters to laser 
printers and bitmap terminals. 

The figure shown below gives an overview of this input-output activity: 



tbl 

grap ^ pic 

eqn 



troff c=:^o»*P"t 
devices 



A 



I ■ 1 

I macro i 
• package ' 



In addition, the figure suggests the characteristic usage of DOCUMENTER'S 
WORKBENCH tools. Rather than one program doing all of the work, several 
specialized programs accomplish a wide variety of diverse functions. This 
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approach enables each component to use an individually tailored language 
particularly suited to its own purposes. That is, DOCUMENTER'S WORK- 
BENCH Software is not top-heavy with a single, lowest-common- 
denominator language that must address a multitude of different demands. 
Rather, each program's "dialect" is dedicated, relatively stream-lined, and 
easy to use. 
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troff traces its origins back to a group of formatters that developed from 
RUNOFF by J. E. Saltzer at MIT during the 1960s. (The name roff actually 
derives from a primitive formatter that Brian Kernighan wrote for his own 
use as a graduate student.) troff 's name was coined to express typesetter 
run-off. It uses formatting commands, called requests, that are interspersed 
through the text to govern processing. A report title, for example, might be 
formed with the following two lines of requests; 

,ce 1 
.ft B 

which would place the next line of text in a centered position and change 
the font to bold, troff provides eighty-five such requests, which are in turn 
effectively multiplied by their respective numerical and alphabetical argu- 
ments. 

In addition, troff uses about forty in-line commands for changing char- 
acter size and typeface, placing special characters, invoking previously 
defined characters or words, and dictating a variety of movements about the 
page, to name a random assortment. For example, \f I changes all succeed- 
ing text to italic, \(co gives the encircled copyright symbol, and \h'numeric 
argument' moves text a distance indicated by a simple numeric argument, 
arithmetic expression, register evaluation, or a combination of these. Argu- 
ments concerning physical dimensions may specify inches, centimeters, 
picas, ems, ens, points, and machine units. 

troff, unlike most of its its related components, does not have indivi- 
dual requests or escape sequences for automatically providing running titles 
at the top of the page, setting up a table of contents, or making concor- 
dances. In contrast to say, the mm macro package, it is intended to permit 
the user a detailed access to the inner workings of DOCUMENTER'S WORK- 
BENCH Software. 

troff is programmable; it has variables, arithmetic arguments, and condi- 
tional tests of many things, including the dimensions of processed text. It 
allows you to define macros that encapsulate a sequence of operations or 
that receive and store processed text. It also permits you to set traps 
(marked page positions) that pass control to macros you have set up for this 
purpose. 
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While this advanced level of detailed access can be indispensable, it is 
not always desirable. Higher-level components, such as mm macros, should 
be used for most text formatting, troff should be thought of as the instru- 
ment for fine-tuning that enables you to accomplish the non-standard pro- 
cessing that more generalized components do not offer. Furthermore, troff 
should be understood as a language especially designed for text program- 
ming. It is capable of sophisticated manipulation of typography, evaluation 
of accumulated text (or "diversions"), placement of graphical elements con- 
tingent upon diversion evaluation, and detailed page control. 
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DOCUMENTER'S WORKBENCH Software uses a number of macro pack- 
ages that enable the user to think in terms of text— title, page headings, 
footnotes— rather than in terms of typography. Each of these packages is 
designed to accomplish specialized tasks ranging from memorandum and 
report preparation to compiling indexes. 

The mm macro package is by far the most powerful and varied of these. 
Formed as a library of troff request and string combinations, these macros 
also allow for limited programmable features, mm provides the tools you 
would need for most text processing: static or floating displays, seven levels 
of numbered page headings, one- or two-column formatting, table-of- 
contents formatter (collected automatically from numbered headings), to 
name a few features. Many of these standard features can be altered to suit 
individual tastes. 

DOCUMENTER'S WORKBENCH Software also includes the mptx macro 
package, used to make permuted indices and the mv macro package for 
making view graphs and projection slides. DOCUMENTER'S WORKBENCH 
Software's indexing tools are mptx, ndx, ptx, and subj. 
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eqn defines a simple language for representing mathematical expres- 
sions. People trained in mathematics can usually learn it in a few minutes; 
people without such training can normally use the language effectively in 
an hour or so. For example: 

a+b over c+d+e = -b sop 2 over pi 

generates this: 



Because eqn runs as a preprocessor, the entire document that contains 
the equation is passed through it before reaching troff, which accepts eqn's 
output as input, eqn does not, however, influence non-mathematical parts 
of the text. It looks for language native to eqn (usually placed between the 
macros ^EQ and .EN) and ignores the rest. 

tbl is trpff's preprocessor for making tables. It uses a language alto- 
gether different from the other preprocessors, which are more oriented 
toward spoken English. It is, nonetheless, a simple language to learn and 
can usually be mastered after one session. The following input lines are an 
example: 
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center, doublebox; 
GfB s s 
c c c 
" c c 
lp8 n n. 
n^ogram Sizes 

Nane Scuroe Object bytes 
Lines (text-Klata) 



\f3troff\fP 
\f3e(p\fP 
\f3tbl\fP 
\f3pic\fP 
\f3grap\fP 
.TE 



8681 73136 

1821 34164 

2581 39936 

3760 83968 

2791 58368 



(The columns of listed data items are separated by tabs.) 
The output looks like this: 



Program Sizes 



Name 


Source 
Lines 


Object bytes 
(text+data) 


troff 


8681 


73136 


eqn 


1821 


34164 


tbl 


2581 


39936 


pic 


3760 


83968 


grap 


2791 


58368 



pic is the facility for drawing figures and diagrams. It places forms 
(boxes, circles, lines, and splines) at absolute positions (using Cartesian coor- 
dinates) or at specified positions relative to already placed objects. The fol- 
lowing is an example of pic input: 
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arxodf "iiqput" above 
box "process" 
arxGw "cwtput" above 
.FB 

V J 

. and it will produce the following illustration: 



input_^ 


process 


outpu^ 







You may follow each object with attributes that control its size and position 
and associated text strings. You may, in addition, plot forms other than the 
ones that pic already supplies. A macro facility allows common operations 
to be encapsulated, and these macros will accept arguments, enabling you to 
build a library of pic drawings which, furthermore, can be modified at each 
usage. 

grap provides a language for describing graphs. Its output is pic input, 
pic in turn feeds requests and strings to troff . By default grap plots input 
numbers as a scatter plot, with automatically computed tick marks. Other 
commands provide control over labels, scaling, logarithmic coordinates, and 
the like. The following is a grap graph: 
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Time 
(in seconds) 



50- 



45- 



Chariots of Fire' 




—\ \ 1 \ T" 

1900 1920 1940 1960 1980 

Olympic 400 Meter Run: Winning Times 



which was produced by the following input: 




frame top invis ri^xt invis 

label left "Tiine" "(in secxandLs)" 

label bot "Olynpic 400 Meter Run: Winning Times" 

draw solid 

1896 54.2 

1900 49.4 

1904 49.2 

1908 50.0 

1980 44.60 

arrow from 1924,51 to 1924,49 

^Chariots of Fire"" ljust at 1924,51 

.G2 



grap, like its near-relative pic, has a macro facility and control-flow features. 
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1. Introduction 



This is a technical discussion of the mm (Memorandum Macro) package, 
a collection of macros that you use to format documents such as letters, 
reports, memoranda, papers, manuals, and books. Macros are formatting 
commands that combine the functions of one or more nroff or troff 
requests. 

Read this technical discussion if you have experience using the mm 
package. If you have never used mm before, you first might v^ant to read 
"The Macro Package mm: a Tutorial" in the User's Guide, Once you decide 
what macros you want to use, refer to this discussion for details about how 
to use them. 



1.1. How this Technical Discussion is Organized 

This first chapter offers definitions of terms that are basic to text pro- 
cessing, specifies conventions that this technical discussion uses, and 
describes formatting concepts relevant to your use of mm. It is provided to 
enrich and clarify the discussion of each facility of mm that follows. 

Assume that a document that you format with mm consists of four seg- 
ments: a parameter setting segment, a beginning, a body, and an end. 
"Chapter 2" discusses these segments, which provide the organizing princi- 
ple for the rest of this technical discussion. "Chapter 3" presents macros 
relevant to formatting the body of a document. In "Chapter 4," macros for 
formatting the beginning of a document are described. "Chapter 5" explains 
end macros. Finally, "Chapter 6" covers miscellaneous macros. In each of 
these chapters, a macro's default formatting action is described followed by 
ways to change this default behavior. For the most part, macros are 
described starting with the simplest usage and progressing to more 
advanced cases. It might be best to read a section in detail only to the point 
where you have enough information to obtain the result that you want and 
then to skim the rest. 

After covering all mm macros, this technical discussion tells you about 
troubleshooting and error messages in "Chapter 7." "Chapter 8" gives a full 
account of using the mm command line to process the files you create. 
Appendices are presented in "Chapter 9." 
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1.2. Definitions 

"Formatter" refers to either the nroff or the troff text-formatting pro- 
gram. These programs have their own tutorials in the User's Guide and their 
own technical discussion in this book. Unless a functional distinction 
requires otherwise, "the formatter" refers to both nroff and troff. 

Requests are built-in commands recognized by the formatter. Although 
you seldom need to use these requests directly when you use mm, this sec- 
tion contains references to some requests. For example, the request .sp 
inserts a blank line in the output at the place that the request occurs in the 
input file. Request names consist of two lower-case letters. For an intro- 
duction to nroff /troff, see "The Formatter nroff/ or The Formatter troff" in 
the User's Guide. For details, refer to the "nroff /troff Technical Discussion" 
in this book. 

Macros are named collections of requests. That is, each macro is an 
abbreviation for a collection of requests that are used repeatedly in the same 
combination. Rather than typing them each time they are needed, you sim- 
ply type the macro that calls them. Sometimes, macros are composed of 
strings and number registers, which are described below. 

The mm package supplies many macros, and you can define additional 
ones. The names of mm macros consist of one or two upper-case letters, so 
if you create your own formatting macros, name them with a lower-case and 
upper-case letter, for example, .pD, to prevent usurping the function of an 
mm macro. Appendix A, the "mm Macro Name Summary," gives a com- 
plete listing of mm macros. 

Strings are character variables, each of which names a string of alpha- 
numeric characters. Page headers, page footers, and lists often contain 
strings. You give a string a value with the .ds (define string) request, and 
you obtain its value by typing its name, preceded by (for 1-character 
names) or "\*(" (for 2-character names). For instance, the string DT in mm 
normally contains the current date, thus the input line 

Today is \»(Dr. 

results in output such as this: 

Today is February 24, 1986. 
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You can replace the current date by redefining the contents of this 
string, for example, 

,ds DT 06/04/85 

or by invoking a macro designed for that purpose {4.1.3). Appendix B pro- 
vides the "mm String Name Summary." 

Number registers, which are similar to integer variables, store the value 
of various text parameters, such as the number of spaces between para- 
graphs (register Ps). The formatter program uses these registers for flags, 
for arithmetic, and for automatic numbering. You can give certain registers 
a value using the .nr request, and you can reference them by preceding 
their names by \n (for 1-character names) or \n( (for 2-character names, for 
example, \n(Ps). 

The following line creates a new number register d, and sets its value to 
one more than that of another new register dd : .nr d l+\n(dd. Some 
number registers are read-only. That is, you can reference them, but you 
cannot change their value. An "mm Number Register Summary" appears as 
Appendix C to this technical discussion. 

1.3. Conventions 

Numbers enclosed in curly braces ( { } ) refer to section numbers. For 
example, this is section {1.3}. 

In the synopses of macro calls, square brackets ([]) surrounding an 
argument show that it is optional. An argument in italics means that you 
are to substitute a legal value for that argument. Ellipses (•••) show that the 
preceding argument may appear more than once. 

In cases where the behavior of the two formatters nroff and troff is 
obviously different, the nroff formatter output is described first with the 
troff formatter output following in parentheses. For instance. 

The title is underlined (italic). 

means that the title is underlined by the nroff formatter and italicized by 
the troff formatter*. 



mm: TECHNICAL DISCUSSION 3 



Introduction 



1.4. Formatting Concepts 

1.4.1. Basic Terms 

A formatter normally fills output lines from one or more input lines. 
You may justify output lines so that both the left and right margins are 
aligned. As you fill lines, you may also hyphenate words as necessary 
(1.4.4). It is possible to turn any of these modes on and off (use .SA (6.2), 
Hy (1.4.4), and the .nf and .fi formatter requests). Turning off line filling 
also turns off justification and hyphenation. 

Certain requests and macros cease line filling, print the input line (of 
whatever length), and begin a new output line after the printed text. This 
printing of a partially filled output line is known as a line break. A few 
formatter requests and most of the mm macros cause a line break. 

You can use formatter requests (1.4.10) with mm, but there are conse- 
quences and side effects that each such request might have. Generally, you 
should use mm macros alone because 

■ They are much easier to use, to control, and later to change the 
overall style of the document. 

■ You obtain complex features (such as footnotes or tables of con- 
tents) with ease. 

■ You are freed from having to define many page control func- 
tions in the nroff or troff languages. 

1.4.2. Arguments and Double Quotes 

For any macro call, a null argument is an argument whose width is 
zero. The preferred form for a null argument, which often has a special 
meaning, is Omitting an argument is not the same as supplying a null 
argument (for example, see the .MT macro (4.1.1)). You can omit arguments 
only at the end of an macro argument list, but you can place null arguments 
anywhere in the list. 
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Enclose any macro argument containing ordinary (paddable) spaces in 
double quotes, or mm will interpret the spaces as argument delimiters. A 
double quote (") is a single character that must not be confused with two 
apostrophes (")/ two acute accents ("), or two grave accents C'). 

You may not use double quotes as part of the value of a macro argument 
or of a string that you use as a macro argument. If you must have double 
quotes in a macro argument value, use two grave accents C*) or two acute 
accents (") instead. This restriction is necessary because many macro argu- 
ments are processed a variable number of times. 

1.4.3. Unpaddable Spaces 

When the formatter justifies output lines to give an even right margin, 
it may append additional spaces to existing spaces in a line. This may dis- 
tort the desired alignment of text. To avoid this distortion, you must 
specify a space that cannot be expanded during justification. There are two 
ways to accomplish this: 

■ You may type a backslash followed by a space (\ ). These 
characters directly generate an unpaddable space. 

■ You may use some seldom-used character to be translated into 
a space on output. 

Because this translation occurs after justification, you may use the 
chosen character anywhere an unpaddable space is desired. The tilde (") is 
often used with the translation request for this purpose. To use the tilde in 
this way, put the following request at the beginning of your document: 
.tr where the tilde is followed by a space. If you must put a tilde in the 
output, you can temporarily "recover" it by inserting .tr " before the place 
where you need it. Repeating the .tr " restores its usage as a space after a 
line break or after the line containing the tilde has been flushed from the 
line buffer. 

You should not translate the tilde character into a space when you use it 
within the .EQ and .EN macros or assigned eqn delimiters. 
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1.4.4. Hyphenation 

Formatters do not hyphenate unless you request it. You can turn on 
hyphenation in the body of the text by typing the following request at the 
beginning of the input file: .nr Hy 1. Section 3.3.1 describes hyphenation 
used within footnotes and across page boundaries. 

If you request hyphenation, the formatters will automatically hyphenate 
words as necessary. However, you may specify hyphenation points for a 
specific occurrence of any word with a special character known as a hyphe- 
nation indicator, or you may specify hyphenation points for a small list of 
words (about 128 characters). If the hyphenation indicator (initially, the 2- 
character sequence •*\%") appears at the beginning of a word, the word is 
not hyphenated. Alternatively, you can use the indicator to show legal 
hyphenation points inside a word. All occurrences of the hyphenation 
indicator disappear on output. 

You may specify a different hyphenation indicator. The circumflex C) 
is often used for this purpose by inserting the following macro at the begin- 
ning of a document input text file: .HC \ Any word containing hyphens or 
dashes (also known as em dashes) is hyphenated immediately after a 
hyphen or dash if hyphenation is necessary, even if the hyphenation func- 
tion is turned off. 

You may supply (via the exception word .hw request) a small list of 
words with the proper hyphenation points shown. For example, to show 
the proper hyphenation of the word "printout," you may specify .hw print- 
out. 

1.4.5. Tabs 

The macros .MX {4.1.1), .TC {5.4}, and .CS (5.6) use the formatter tabs 
.ta request to set tab stops. The default values of tab settings are every eight 
characters in the nroff formatter, and every inch in the troff formatter. 
You may set tabs to other values. 

For the nroff formatter, default tab setting values are 8, 16, 24, 32, 40, 
160 characters for a total of 20 tab stops. That is, the default tab settings 
correspond to the following example: 

.ta 8 16 24 32 40 48 56 64 72 . . . 160 
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You may separate tab settings with commas, spaces, or any other non- 
numeric character. You may set tab stops in any horizontally oriented scale. 

The formatter interprets a tab character with respect to its position on 
the input line rather than its position on the output line. In general, you 
should only put tab characters on lines after you turn off line filling (.nf) 
{1.4.10}. The tbl program {3.7} changes tab stops but does not restore 
default tab settings. 

1.4.6. Bullets 

The troff formatter provides the bullet character (•)• For compatibility 
with troff, mm also provides a bullet string: \*(BU. The bullet list (.BL) 
macro {3.2.5} uses this string to generate automatically the bullets for bullet 
listed items. 

1.4.7. Dashes, Minus Signs, and Hyphens 

The troff formatter distinguishes among the dash, the minus sign, and 
the hyphen, but the nroff formatter does not. 

■ If you intend to use nroff, you may only use the minus sign 
(-) for the minus, hyphen, and dash. 

■ If you plan to use troff primarily, you should follow troff 
escape conventions. 

■ If you plan to use both formatters, take care during input text 
file preparation. Unfortunately, these graphic characters can- 
not be represented in a way that is both compatible and con- 
venient for both formatters. 

The following approach is suggested: 

Dash Type "\*(EM" for each text dash for both nroff and troff for- 
matters. This string generates an em dash in the troff for- 
matter and two dashes (-) in the nroff formatter. Dash list 
(.DL) macros {3.2.5} automatically generate the em dash for 
each list item. 

Hyphen Type and use as is for both formatters. The nroff for- 
matter will print it as is. The troff formatter will print - (a 
true hyphen). 
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Minus Type "\-" for a true minus sign regardless of formatter. The 
nroff formatter will ignore the \. The troff formatter will 
print — (a true minus sign). 

1.4.8. Trademark String 

A trademark string \*(Tm is available with mm. This places the letters 
"TM" one-half line above the text that it follows. For example. 

The 
.1 

lMD^f1\*(1hi 

system V User's Guide 

.R 

is available fron the library. 

yields 

The 

Sifstcm V User's Guide 

is available from the library, 

1.4.9. BEL Character 

Many macros use the non-printing character BEL as a delimiter to com- 
pute the width of an argument or to delimit arbitrary text in page headers 
and footers {3.4}, headings (3.5), and lists (3.2). This is to decrease the pos- 
sibility that an argument might contain a character identical to one delimit- 
ing it, which would produce undesirable results. 

1.4.10. Use of Formatter Requests 

You need not use most formatter requests with mm since it provides the 
corresponding formatting functions in a more straightforward fashion. The 
following requests can be useful with mm: 



8 TECHNICAL DISCUSSION 



Introduction 



.af 


Assign format 


.br 


Break 


.ce 


Center 


.de 


Define macro 


.ds 


Define string 


.fi 


Fill output lines 


.ft 


Change font 


.hw 


Exception word 


.Is 


Line spacing 


.nf 


No filling of output lines 


•nr 


Define and set number register 


.nx 


Go to next file (does not return) 


.rm 


Remove macro or string 


.rr 


Remove register 


.rs 


Restore horizontal spacing 


.so 


Switch to source file and return 


•Sp 


Space 


.ta 


Tab stop settings 


.ti 


Temporary indent 


.tl 


Title 


.tr 


Translate 


.sy 


Issue command(s) to UNIX system 



The .fp, .Ig, and .ss requests are sometimes useful for the troff for- 
matter. In general, it is best not to use too many troff requests in conjunc- 
tion with mm. 
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A document that you format with mm consists of four segments, any of 
which you may omit. If you include any of these segments, you must put 
them in the following order: 

. ■ The parameter setting segment sets the general style and 

appearance of a document. Here, you control page length and 
width, margin justification, numbering styles for heading and 
lists, page headers and footers, proprietary markings, among 
other properties of the document. Also, you can add macros or 
redefine existing ones. You can omit this segment entirely if 
you are satisfied with mm's default values; the segment pro- 
duces no output but performs only the formatter setup for the 
rest of the document. Here is an example of a parameter setting 



segment: 




.nr Ls 


specifies that no spacing occurs between any list 




items 


.nr CI 4 


saves up to 4th level section headings for table of 




contents 


.nr Pi 7 


sets paragraph indentation to 7 spaces 


•nr Hs 4 


specifies a line of space between text and section 




headings up to 4th level 



The beginning consists of those items that occur only once at 
the start of a document: a memorandum title, names, the date, 
and so on. Here is the beginning of a formal memorandum: 



.PM PM3 specifies a proprietary marking of 

"SEE PROPRIETARY NOTICE ON COVER PAGE" 

•TL specifies that line following the macros, "Work 

Report," is the title 

.AU "J. Smith" JS 

formats information about the author, "J. Smith" 
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.MT sets the formal memorandum type 

Here is the beginning of a business letter: 

.WA signals the beginning of the writer's address 

.WE signals the end of the writer's address 

JA signals tKe beginning of the addressee's address 

.IE signals the end of the addressee's address 

.LO SA "Dear Jane/ 

sets the letter's salutation to "Dear Jane/ 

XT BL specifies a Blocked type business letter 



■ The body of a document is the text itself. It may be as little 
text as a single paragraph or as much as hundreds of pages. 
It may have a hierarchy of section headings up to seven lev- 
els deep {3.5}, and you may automatically number section 
headings and save them to generate the table of contents, 
mm provides five additional levels of subordination by a set 
of list macros for automatic numbering, alphabetic sequenc- 
ing, and "marking" of list items {3.2.1}. You can put various 
types of displays {3.6}, tables {3.7}, figures {3.9}, equations 
{3.8}, references {5.7}, and footnotes {3.3} in the body. 

■ The end contains items that usually occur at the close of a 
document. Included are signature(s), and lists of notations 
(for example, 'Copy to' lists) {5.3}, which may occur at the 
beginning of the document {4.2.1}.) You may call certain 
macros at the end to print information that is wholly or par- 
tially derived from the rest of the document such as the table 
of contents or the cover sheet {5.6}. 

For example, 

.FC prints the formal closing, "Yours very truly," 

.SG prints the name(s) specified with .AU 

,NS begins a "Copy to" list 
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•NE signals the end of the "Copy to" list 

•TC generates a table of contents 

The existence and size of these four segments varies widely among 
different document styles. Although a specific item of a segment (such as 
date, title, author names, and so on) may dififer depending on the document, 
there is a uniform way of typing it into an input text file. To make it easy 
to edit or revise input file text at a later time: 

■ Keep input lines short. 

■ Break lines at the end of clauses. 

■ Begin each new sentence on a new line. 
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the Body of a Document 



3.1. Formatting 



Paragraphs (.P) 



To use .P, which stands for paragraph, your input would look like this: 



.P without an argument forces left justification (the first line begins at 
the left margin), as does .P 0. .P 1 indents the first line five spaces unless 
you specify another amount of indentation by changing the value contained 
in the number register Pi. For example, to indent particular paragraphs ten 
spaces, type the following line once at the top of your file: .nr Pi 10 and 
then use .P 1 before every paragraph that you want indented. 

3.1.1. Paragraph Type (Pt) 

Suppose that you want all paragraphs indented. Rather than type .P 1 , 
you can set the Pt number register, which controls the paragraph type. The 
initial value of Pt is 0, which provides left-justified paragraphs. Force every 
paragraph in your output to be indented by inserting the following line at 
the beginning of the document input file: .nr Pt 1. You may specify the 
amount of indentation by setting Pi as before if you do not want to use the 
default. 

Indent ail paragraphs except after headings, lists, and displays (dis- 
cussed below) by entering the following at the beginning of your document 
input file: .nr Pt 2. 

Both the Pi and Pt register values must be greater than zero to indent 
paragraphs. Values that you use to specify indentation must be unsealed 
and are treated as character positions (ens), nroff understands an en to be 
equal to the width of a character, troff understands an en to be the number 
of points (1 point - 1/72 of an inch) equal to half the current point size. 

Regardless of the value of Pt, .P 1 causes indentation by the amount 
specified by the register Pi. If .P occurs inside a list, the indent (if any) of 
the paragraph is added to the current list indent {3.2.1}. 



.P [type] 
Text 
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3.1.2. Numbered Paragraphs (Np) 

Produce numbered paragraphs by setting the Np register to 1, which 
numbers paragraphs within first level headings. Use the .nP macro rather 
than the .P macro to produces paragraphs that are numbered within second 
level headings. 

.H 1 "FIRST HEADING" 
.H 2 "Secjcnd Headiiig" 
.nP 

These numbered paragraphs cxmtain a "double-line indent," 
in vtoch the text of the second line aligns vdth the teact 
of the first line, so that the number stands cut. 
The third and following lines of a numbered paragraph return 
to the left margin. 

produces 

- 1 - 



JJ?ST HEADING 
1.1 S econd_ Head i 115 

1.01 These numbered paragraphs contain a double-line 
indent 

in which the text of the second line aligns with the text of 
the first line, so that the number stands out. The third and 
following lines of a numbered paragraph return to the left 
margin. 

3.1.3. Spacing Between Paragraphs (Ps) 

The Ps number register controls the amount of spacing between para- 
graphs. By default, the formatter sets Ps to 1, yielding one blank space 
(one-half vertical space). Giving Ps a value of yields no space between 
paragraphs. 
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3.2. Formatting Lists 

3.2.1. General Characteristics of Lists 

mm provides a convenient way to create lists automatically. All lists are 
composed of three basic parts: 

■ A list-initialization macro determines the line spacing, inden- 
tation, marking with special symbols, and numbering or 
alphabetizing of list items. Available list-initialization macros 
are 



.AL 


Automatically Incremented List 


.ML 


Marked List 


•VL 


Variable-Item List 


•BL 


Bullet List 


.DL 


Dash List 


•RL 


Reference List 



If you do not provide arguments to the list-initialization macro, text 
will be indented by a default number of spaces from the indent 
currently in force. This default varies as a function of what type of 
list you call. Change the indentation value by placing the desired 
indentation into the number register Li. 

■ One or more list-item macros (.LI) identifies each item in 
your list. List-item macros are followed by the text of the 
corresponding list item: 

.LI [mark [1] ] 
Text 

Use the .LI macro with all list types and for each list item. .LI normally 
causes output of a single blank line before its list item although you may 
suppress this feature by setting the Ls (list space) register. Ls is set to the 
innermost list level in nested lists for which spacing is done. For example, 
.nr Ls specifies that no spacing will occur around any list items. The 
default value for Ls is 6 (which is the maximum list nesting level). 
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You may supply arguments to .LI. 

■ If you give .LI no arguments, it labels the item with the mark 
specified by the most recent list-initialization macro (for exam- 
ple, .BL sets the mark to be a bullet). 

■ If you give .LI a single argument, that argument is output 
instead of the current mark. 

■ If you give .LI two arguments, the first argument becomes a 
prefix to the current mark, allowing you to emphasize one or 
more items in a list. 



For example, 

.BL 
.LI 

iMs is a bullet item. 
.LI + 

This replaces the bullet with a "plus." 
.LI + 1 

This uses a "plxjs" as prefix to the tullet. 
.LE 

when formatted yields 

- 1 - 



•o This is a bullet item. 

+ This replaces the bullet with a "plus." 
+ -o This uses a "plus" as prefix to the bullet. 

Do not put ordinary (paddable) spaces into the mark because the align- 
ment of items is lost if you justify the right margin {1.4.3}. 

If the current mark in the current list is a null string, and the first argu- 
ment of .LI is omitted or null, the resulting effect is that of a hanging 
indent. That is, the first line of the following text is "outdented," starting at 
the same place where the mark would have started {3.2.4}. The list-end 
macro (.LE) ends the list: .LE [1]. If you specify an argument to .LE, it out- 
puts a blank line. 
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The list-initialization macro saves the previous list status (indentation 
marking style, and so on), and changes the status to that of the new initiali- 
zation macro. The list-end macro restores the status of the previous list 
unless there is no previous list. In that case, the list-end macro restores the 
status to that existing before the list-initialization macro call. This informa- 
tion about list status is important to remember when you format nested 
lists, which are described below. 

3.2.2. Automatically Incremented Lists (.AL) 

.AL stands for automatically incremented list. The general syntax of the 
macro is as follows: .AL [type [text-indent [1] ] ]. 

If you do not specify arguments, the list is numbered, and text is 
indented the value of Li, initially six (five) spaces from the indent in force 
when the .AL is called, leaving room for a space, two digits, a period, and 
two spaces before the text. 



Do not scale values that specify indentation. These values are scaled in 
terms of "character positions " (ens). 



Specifying a type produces a different type of sequencing. The value of 
type in the table below shows the first element in the sequence desired. 



Argument 


Interpretation 


1 


Arabic (default for all levels) 


A 


Upper-case alphabetic 


a 


Lower-case alphabetic 


I 


Upper-case roman 


i 


Lower-case roman 



Figure 1: Arguments to the .AL Macro 



If you specify a text-indent argument, the formatter uses it as the number 
of spaces from the current indent to the text of the list items. This value 
overrides that in Li for the list where you use the argument. 
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If you give a third argument, a blank line will not separate items in the 
list. However, a blank line will occur before the first item. 

3.2.3. Marked Lists (.ML) 

The .ML macro expects you to specify an arbitrary mark that may consist 
of one or more characters: .ML mark [text-indent [1] ]. Text is indented text- 
indent spaces if the second argument is not null; otherwise, the text is 
indented one more space than the width of mark. If the third argument is 
specified, no blank lines will separate items in the list. 

Do not put ordinary (paddable) spaces into the mark because the align- 
ment of items is lost if you justify the right margin. Here's a file containing 
a marked list before formatting: 

.ML $ 
.LI 

Scdes are up, 
.LI 

Profits are up. 
.LE 

Here's that same list after formatting: 

- 1 - 

$ Sales are up. 
$ Profits are up. 

3.2.4. Variable-Item Lists (.VL) 

Another version of the marked list is the "variable-item" list that you 
call with the .VL macro: .VL text-indent [mark-indent [1] ]. When you begin 
a list with a .VL macro, there is effectively no current mark; you provide 
each .LI its own mark. This form is typically used to display definitions of 
terms or phrases. 
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.tr - 

.VL 1.0 

.LI requests 

are the most elenientary text-fontBttijig OGnEcand available with 
DOCUMEHTER'S VOUCHEUCH Software. 
.LI macros 

are oollections of single foncatting OGmxands called by a 
single name. 

.LI d€nc>nstration_of_a_loiKr^mark: 
This item shows the effect of a long mark; one space 
separates the mark from the beginning of the text. 
.LI - 

Ihis item effectively has no nark becaxsse the tilde 

is translated into a space. 

.LE 

when formatted yields 

- 1 - 



No hyphenation. Automatic hyphenation is turned off. Words 
containing hyphens (for example, mother-in-law) may still 
be split across lines. 

Hyphenate. Automatic hyphenation is turned on. 

Hyphenation indicator character is set to "c" or removed. 
During text processing, the indicator is suppressed and 
will not appear in the output, Prepending the indicator to 
a word has the effect of preventing hyphenation of that 
word . 

As with the other list types, text-indent provides the distance from 
current indent to beginning of the text. Mark indent produces the number 
of spaces from current indent to beginning of the mark, and it defaults to 
if omitted or null. If you specify a third argument, no blank lines will 
separate items in the list. Again, do not put ordinary (paddable) spaces into 
the mark because the alignment of items is lost if you justify the right mar- 
gin. 
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3.2.5. Bullet, Dash, and Reference Lists (.BL, .DL, .RL) 

To initialize any of these lists, type: .BL or .DL or .RL [text-indent [1] ] 

A bullet (•) followed by one space marks each list item. As always, if 
you specify a text-indent argument, it overrides the default indentation. In 
the default case, the text of a bullet list lines up with the first line of 
indented paragraphs (set with the number register Pi {3.1}). 

With each of these list types, no blank lines will separate items in the 
list if you specify a second argument. A dash ( — ) followed by one space 
marks each list item of a dash-list. Here's an example of input: 

.DL 
•LI 

Prepare documents and tables 
.LI 

Develop new mcro ociiiTBnds 
.LE 

- 1 - 



- Prepare documents and tables 

- Develop new macro commands 

An .RL macro call begins an automatically numbered list that encloses 
the numbers in square brackets ([]). 

Here's the input: 

.PL 8 1 
.LI 

DOCUHEXirER's WQRKBEUCH User^s Guide 
.LI 

DOCCMEMTEH'S WORKBENCH Technical Discussion 

and Reference Manual 

.LI 

DDCUMEMTBR'S WORKHENCH Handbook 
.LE 

The output is as follows: 
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- 1 - 



[1] DOCUHENTER'S WORKBENCH User's Guide 

[2] DOCUHENTER'S WORKBENCH Technical Discussion and 

Reference Manual 
[3] DOCUHENTER'S WORKBENCH Handbook 



3.2.6. Nested Lists 

Lists may be nested up to six levels. Here is an example of nested lists: 

.AL 
•LI 

Develop loethods for poxxiuclng 

docuznentaticn 

•LI 

Perfccm duties resulting from the development of these methods. 

For exanple, 

.BL 

•LI 

Use text processing to: 

•DL 

•LI 

Prepare documents and tables 
•LI 

Develop nev/ macro oonnends 

•LE 

•LI 

Serve as a point of oontact with printers and 

distributors. 

.!£ 

•LI 

If the job holder's interests and writing skills natch the 
needs of the Technical Writing Staff, 
write documents. 

Here's how that same list looks after it has been formatted. 
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- 1 - 



1 . Develop methods for producing documentation 

2. Perform duties resulting from the development of these 
methods. For example; 

o Use text processing to: 

- Prepare documents and tables 

- Develop new macro commands 

o Serve as a point of contact with printers and 
distributors . 

3. If the job holder's interests and writing skills 
matched the needs of the Technical Writing Staff, 
there might be an opportunity to write documents . 

In this example, the first list-initialization macro that occurs is .AL. Since 
you specify no argument for .AL, the formatter numbers list items in 
sequence with Arabic numerals. Before the list-end macro associated with 
.AL occurs, another list-initialization macro appears, .BL. Now, a bullet 
marks each list item. Finally, .DL marks list items with dashes. When the 
.LE associated with .DL occurs, a bullet marks list items again, since .BL was 
the list-initialization macro active before the dash list. When ,LE ends the 
bullet list, list items are numbered until .LE occurs again. 

Every time a new list-initialization macro occurs, the list status (indenta- 
tion, marking style, and so on) changes. .LE restores the status generated 
by the immediately preceding list-initialization macro. 

3.2.7. List-Begin Macro and Customized Lists 

List-initialization macros described above suffice for almost all cases. 
However, you may obtain more control over the layout of lists by using the 
basic list-begin macro (,LB). The syntax is as follows: 

•LB text 'indent mark-indent pad type [mark [LI -space [LB-space ] ] ] . 

The other list-initialization macros use .LB. Its arguments are as follows: 
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■ The text-indent argument that provides the number of spaces 
that text indents from the current indent. Normally, this value 
is taken from the Li register (for automatic lists) or from the Pi 
register (for bullet and dash lists). 

■ The combination of mark-indent and pad arguments determines 
the placement of the mark. The mark is placed within an area 
(called mark area) that starts mark-indent spaces to the right of the 
current indent and ends where the text begins (that is, ends 
text-indent spaces to the right of the current indent). The mark- 
indent argument is typically 0. 

■ Within the mark area, the mark is left justified if the pad argu- 
ment is 0. If pad is a number n (greater than 0), then n blanks 
append to the mark; the mark-indent value is ignored. The 
resulting string immediately precedes the text. The mark is 
effectively right justified pad spaces immediately to the left of 
text. 

■ The arguments type and mark interact to control the type of 
marking used. If type is 0, simple marking is performed using 
the mark character(s) found in the mark argument. If type is 
greater than 0, automatic numbering or alphabetizing is done; 
and mark is then interpreted as the first item in the sequence to 
be used for numbering or alphabetizing. That is, it is chosen 
from the set (1, A, a, I, i) {3.5.2.6}. This is summarized below: 



Type 


Mark 


Result 





>0 
>0 


omitted 

string 

omitted 

1, A, a, I, i 


hanging indent 
string is the mark 
Arabic numbering 
automatic numbering or 
alphabetic sequencing 



Figure 2: Type and Mark for .LB 



Each non-zero value of type from one to six selects a different way 
of displaying the marks. The following table shows the output 
appearance for each value of type, where x is the generated number 
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or letter: 



Value 



Appearance 



1 
2 
3 
4 
5 
6 



{x] 



X) 
(X) 
[X] 



X, 



Figure 3: Appearance for Values of .LB Type 



■ Do not put ordinary (paddable) spaces in the mark. 

■ The Ll-space argument gives the number of blank lines (each 
one-half of the current vertical spacing) that should be output 
by each .LI macro in the list. If omitted, Ll-space defaults to 1; 
use the value to obtain compact lists. If Ll-space is greater than 
0, the .LI macro issues a .ne request for two lines just before 
printing the mark. 

■ The LB'Space argument is the number of blank lines (each one- 
half the vertical spacing) to be output by .LB itself. If omitted 
LB-space defaults to 0. 

There are three combinations of Ll-space and LB-space: 

■ The normal case is to set Ll-space to 1 and LB-space to yielding 
one blank line before each item in the list; such a list is usually 
ended with a .LE 1 macro to end the list with a blank line. 

■ For a more compact list, Ll-space is set to 0, LB-space is set to 1, 
and the .LE macro is used at the end of the list. The result is a 
list with one blank line before and after it. 

■ If both Ll-space and LB-space are set to and the .LE macro is 
used to end the list, a list without any blank lines will result. 



24 TECHNICAL DISCUSSION 



Formatting the Body of a Document 



3.2.8. Defining List Structures 



This section is intended only for people who write formatter macros. If 
Nore you have not written macros, or if you are content with the lists that mm 
I provides by default, you may skip this section. To learn about writing mac- 
I ros, check the "User's Guide" for The Formatter nroff/ "The Formatter 
troff/ and check this book for the *'nrotf/troff Technical Discussion," 



If a large document requires complex list structures, it is useful to be 
able to define the appearance for each list level only once instead of having 
to define it at the beginning of each list. For example, you might define a 
generalized list-initialization macro in such a way that causes each list- 
nesting level to behave differently from its predecessor or successor. Sup- 
pose you want levels 1 through 5 of lists to have the following appearance: 

- 1 - 



A. 



[1] 



a) 



+ 



The following code defines a macro (.aL) that always begins a new list 
and determines the type of list according to the current list level. As the 
example demonstrates, the mm list macros use the number register :g to 
determine the current list level; it is if there is no currently active list. 
Each call to a list-initialization macro increments :g, and each .LE call decre- 
ments it. 
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.de aL 

A" register g is used as a local tenporary 

A" to save :g before it is changed below 

.nr g \n( :g 

.if \\ng=0 .AL A \" give me an A. 

.if \\ng=1 .LB \n(Li 1 4 

.if \\ng=2 .BL \" give me a bullet 

.if \Njig=3 .LB \n(Li 2 2 a 

.if \\ng=4 .ML + \" give me a + 



Now, you can use this macro (with .LI and .LE) instead of .AL, .RL, .BL, 
.LB, and .ML. For example, the following input: 

.aL 
.LI 

first line. 

.aL 

•LI 

second line. 

.LE 

•LI 

third line. 
.LE 

will yield 

- 1 - 



A, first line. 

[ 1 ] second line . 

B . third line . 

You could take another approach to lists that is similar to the .H 
mechanism. The list-initialization as well as the .LI and the .LE macros are 
all included in a single macro. That macro (called .bL below) requires an 
argument to tell it what level of item is required; it adjusts the list level by 
either beginning a new list or setting the list level back to a previous value, 
and then it issues a .LI macro call to produce the item: 
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.de bL 

A" if argument, that is the level 
.ie \\n( .$ .nr g \\$1 
A" if no argument, yjse current level 
.el .nr g \\n( :g 

.if (\\ng--\\n(:g)>1 .)D " ••ILLEIGAL SKIPPING OF LEVEL " 

A" increasiJig level by more than 1 

A" if g > :g, begin new list 

A" ana reset g to current level ( .aL changes g) 

.if \\ng>\\n(:g \{.aL \\ng-1 

nr g \\n( :g\} 
A" if :g > g, prune back to correct level 
.if \\n(:g>\\ng .DC \\ng 

A" if :g = g, stay within current list 

,LI \" always, get out an item 



Calling .bL without arguments causes it to stay at the current list level. 
The .LC macro (List Clear) removes list descriptions until the level is less 
than or equal to that of its argument. For example, the .H macro includes 
the ".LC 0" call. If you want to resume text at the end of a list, insert the 
call ".LC 0" to clear out the lists completely- The example below illustrates 
the small amount of input needed by this approach. The input text 

The quick brown fox jun?)ed over the lazy dog's back. 
,bL 1 

first line. 
.bL 2 

second line. 
.bL 1 

third line. 
.bL 

fourth line. 
.LC 

fifth line. 

yields 
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The quick brown fox jumped over the lazy dog's back. 

A. first line . 

[ 1 ] second line. 

B. third line. 

C. fourth line . 
fifth line. 



3.3. Footnotes (.FS, .FE) 

There are two macros that delimit the text of a footnote. The .FS (foot- 
note start) macro marks the beginning of the text of a footnote, and the .FE 
(footnote end) macro marks the end: 

.FS [label] 
Footnote text 

These macros form a macro pair; you cannot use one macro without the 
other. Mark the footnoted line of your paper or memo with '^*F" or with 
the optional label. If you mark your footnoted line with A*F/ do not supply 
a label with .FS; footnotes will be numbered automatically. If you use a 
footnote label, follow .FS with the label you have chosen (.FS label). 

The footnote text (enclosed within the macro pair) should immediately 
follow the word that you footnote in the input text, so that '^*F'* or label 
occurs at the end of a line of input and the next line is the .FS macro call. 
Consider the following examples. The first is input for a numbered foot- 
note: 

Uiis is the line ocntaimng the wcacd\*F 
.FS 

This is the text of the footzx>te. 
•FE 

to be footnoted. 
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Next is a labeled footnote: 

This is a labeled* 
.FS ♦ 

The footnote is labeled with an asterisk. 
.FE 

footDiiote. 

Appendix F shows "Sample Footnotes." 

Your memo or paper may contain both user-labeled and automatically 
numbered footnotes. Another .FS, a .DS (static display {3.6.1)), or a .DF (a 
floating display {3.6.2}) are not permitted between .FS and .FE macros. If 
you do not end the text of a footnote with .FE, you will probably cause a 
formatter error. If you require footnotes in the title, the abstract or in a 
table, note that only labeled footnotes appear properly. Everywhere else, 
automatically numbered footnotes work fine. 

3.3.1. Changing the Format of Footnote Text (.FD) 

Use .FD to control the hyphenation, right margin justification, and 
indentation of footnote text, and to control left or right justification of the 
footnote label when you indent footnote text: .FD [arg [1] J. 

The leftmost column of the following table shows the legal arguments 
to .FD [arg]. The remaining four columns show the hyphenation, 
justification and indentation that you obtain with each value of [arg]. For 
additional information concerning the .ad, .na, .hy, and .nh requests (which 
stand for adjust, no adjust, hyphenation, and no hyphenation, respectively), 
see the "nroff /troff Technical Discussion" in this book. 
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Argument 


Hyphenation 


Adjust 


Text 
Indent 


Label 
Justification 


0» 


.nh 


.ad 


yes 


left 


1 


.hy 


.ad 


yes 


left 


2 


.nh 


.na 


yes 


left 


3 


.hy 


.na 


yes 


left 


4 


.nh 


.ad 


no 


left 


5 


•hy 


.ad 


no 


left 


6 


.nh 


.na 


no 


left 


7 


.hy 


.na 


no 


left 


8 


.nh 


.ad 


yes 


right 


9 


.hy 


.ad 


yes 


right 


10*» 


.nh 


.na 


yes 


right 


11 


.hy 


.na 


yes 


right 



* default for the mmt command line 
** default for mm command line 

Figure 4: Arguments to the .FD Macro 
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An argument of 11 or greater is equivalent to .FD 0. The effect of a null 
or omitted argument varies according to the command line you use to pro- 
cess your file. If you use the mm command, a null or omitted argument is 
equivalent to •FD 10; if you use the mmt command, a null or omitted argu- 
ment is equivalent to .FD 0. 

If you specify the second argument, automatically numbered footnotes 
begin again v^ith 1 when a first-level heading is encountered. This is most 
useful with the "section-page" page numbering scheme. As an example, the 
input line .FD 1 maintains the default formatting style and causes foot- 
notes to be numbered afresh after each first-level heading in a document. 

Hyphenation across pages is inhibited by mm except for long footnotes 
that continue to the following page. If you permit hyphenation, it is possi- 
ble for the last word on the last line on the current page footnote to be 
hyphenated. To avoid this, you may specify an even .FD argument. 

Footnotes are separated from the body of the text by a short line rule. 
Those that continue to the next page are separated from the body of the text 
by a full-width rule. In the troff formatter, footnotes are set in type two 
points smaller than the point size used in the body of text. 

3.3.2. Spacing Between Footnote Entries (Fs) 

Normally, one blank line (a 3-point vertical space) separates footnotes 
when more than one occurs on a page. To change this spacing, set the Fs 
number register to the desired value. For example, .nr Fs 2 will cause two 
blank lines (a 6-point vertical space) to occur between footnotes. 



3.4. Page Headers and Footers 

A page header (or header) is text that occurs at the top of pages, while a 
page footer (or footer) occurs at the bottom of pages. By default, the mm 
macro package centers the page number surrounded by dashes at the top of 
every page (except the first page of a formal memorandum) and does not 
print a page footer. 

Change this default by using a mm page header macro or a page footer 
macro. Usually, you change a header or footer once at the beginning of the 
document, but you may change the header or footer as many times as you 
wish. You may specify a line on every page, a line on the even page only, 
and a line on the odd page only; thus, the header and footer may contain as 
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many as two lines of text: the line printed at the top of every page and the 
line for the even- or odd-numbered page. 

3.4.1. Page Headers (.PH) 

Use the .PH macro to specify a header for the top of every page: .PH 
[arg]. The initial value of [arg] for .PH is the centered page number sur- 
rounded by dashes. 

For all header and footer macros (.PH, .EH, .OH, .PF, .EF, and .OF) the 
argument [arg] is of the form: 

"'left-part 'center-part 'right-part' " 

The formatter left justifies the left-part, centers the center-part, and 
right justifies the right-part of the header or footer argument that you pro- 
vide. For example, 

.PH " ' John Smith' ' Technical Writing Staff' " 
produces 

John Smith Technical Writing Staff 

at the top of every page of the document (after you call .PH). In the exam- 
ple above, the center part of the header is left unspecified. If it is incon- 
venient to use apostrophe C) as the delimiter because an apostrophe occurs 
within one part, you may uniformly replace the apostrophe with any other 
character. For example, 

"♦Let's put this left»This center»Let's put this right*" 

3.4.2. Even-Page Header and Odd-Page Header (.EH, .OH) 

The .EH macro supplies a line to be printed at the top of each even- 
numbered page immediately following the page header: .EH [arg] 

The .OH macro is the same as the .EH except that it applies to odd- 
numbered pages: .OH [arg]. The initial value of [arg] for both .EH and .OH 
is a blank line. 

3.4.3. Page Footer (.PF) 

The .PF macro specifies the line that is to appear at the bottom of every 
page: .PF [arg]. The initial value of the page footer is a blank line. 



32 TECHNICAL DiSCUSSION 



Formatting the Body of a Document 



3.4.4. Even-Page Footer, Odd-Page Footer, and First-Page Footer 

(.EF, .OF) 

The .EE macro supplies a line to be printed at the bottom of each even- 
numbered page immediately preceding the page footer: .EE [arg]. The .OF 
macro supplies a line to be printed at the bottom of each odd-numbered 
page immediately preceding the footer: •OF [arg]. The initial value of these 
footers is a blank line. 

3.4.5. Headers and Footers for the Memorandum and Released 
Paper Style 

In a memorandum or a released-paper style document, the page header 
on the first page is automatically suppressed provided a break does not 
occur before the .MT macro is called. Macros and text in the following 
categories do not cause a break and are permitted before the memorandum 
types (.MT) macro: 

■ Memorandum and released-paper style document macros 
(.TL, .AU, .AT, .TM, .AS, .AE, .OK, .ND, .AF, .NS, and .NE) 

■ Page headers and footers macros (.FH, .EH, .OH, .PF, .EE, and 
.OF) 

■ The .nr and .ds requests. 

3.4.6. Strings and Registers in Header and Footer Macros 

String and register names may be placed in arguments to header and 
footer macros. If the value of the string or register is to be computed when 
the respective header or footer is printed, invocation must be escaped by 
four backslashes. This is because string or register invocation is processed 
three times: 

1. As the argument to the header or footer macro 

2. In a formatting request within the header or footer macro 

3. In a .11 request during header or footer processing. 

In paragraphs, you only need one backslash (for example, \nP). In a page 
header, you need four; in a static display, you need two, and so on. 
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For example, the mm page number register P must be escaped with four 
backslashes to specify a header in which the page number is to be printed at 
the right margin, for example: .PH ""'Page \\\\nP'" creates a right-justified 
header containing the word "Page" followed by the page number. Simi- 



If you make the string a] contain the current section heading that is to 
be printed at the bottom of each page, the .PF macro call is .PF ""\\\\*(af '". 

If you use only one or two backslashes, the footer would print a con- 
stant value for aj, namely, its value when .PF appeared in the input text. 

3.4.7. Top and Bottom (Vertical) Margins (.VM) 

The .VM (vertical margin) macro allows you to specify additional space 
at the top and bottom of the page: .VM [top] [bottom]. This space precedes 
the page header and follows the page footer. A null top or bottom argument 
or an argument of puts no additional space before the header or after the 
footer. 

top and bottom are two unsealed arguments that are treated as v's 
(default vertical line spaces: see the "nroff /troff Technical Discussion"). For 
example, .VM 10 15 adds 10 blank lines to the default top of page margin 
and 15 blank lines to the default bottom of page margin. Both arguments 
must be positive (you may decrease default spacing at the top of the page by 
redefining .TP {3.4.9)). 

3.4.8. Private Documents (Pv) 

The word "PRIVATE" may be printed, centered, and underlined on the 
second line of a document (preceding the page header). This is done by set- 
ting the Pv register value: .nr Pv value. Possible values are as follows: 




Value 



Meaning 




1 
2 



do not print PRIVATE (default) 
PRIVATE on first page only 
PRIVATE on all pages 



Figure 5: Values for the Pv Number Register 
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If value is 2, the user definable .TP macro may not be used because mm 
uses the .TP macro to print "PRIVATE" on all pages except the first page of a 
memorandum on which .TP is not invoked. 

3.4.9. Generalized Top-of-Page Processing 

This section is intended only for people who write formatter macros. If 
you have not written macros, or if you are content the way that mm han- 
dles top-of-page processing by default, you may skip this section. 



NOTE 



During header processing, mm invokes two user-definable macros: 

■ The .TP (top of page) macro is invoked in the environment 
(refer to .cv request) of the header. 

■ The .PX is a page header user-exit macro that is invoked 
(without arguments) when the normal environment has been 
restored and with the "no-space" mode already in effect. 

The effective initial definition of .TP (after the first page of a document) 

is 

.de TP 
,sp 3 

.tl \\«( }t 
.if e 'U \\»( }e 
.if o 'tl \\*{ }o 
.sp 2 

The string }t contains the header, the string )e contains the even-page 
header, and the string }o contains the odd-page header as you define them 
with the .PH, .EH, and .OH macros, respectively. To obtain more special- 
ized page titles, you may redefine the .TP macro {3.5}. Formatting done 
within the .TP macro is processed in an environment different from that of 
the body. For example, to obtain a page header that includes three centered 
lines of data (document number, issue date, and revision date) you could 
define the .TP as follows: 
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.de TP 
.sp 
.ce 3 

777-888-999 
Iss, 2, AUS 1985 
Pev. 7, SEP 1985 
.sp 



Use .PX as a user-defined macro to specify text that you want to appear 
at the top of each page after the normal header. 

.de FX 
.ce 

RESraiCTED rNPORMAlTICN: FOR TOUR EXES ONLY 



3.5. Section Headings (.H) 

mm provides two types of section headings: numbered and unnum- 
bered. To create a numbered section heading, type 

.H level [heading-text [heading-suffix] ] 
Text 

The level argument provides the numbered heading level. There are 
seven heading levels; level 1 is the highest, level 7 is the lowest. The 
heading-text argument is the text of the heading. For example, 

.H 1 "FIBST-LEVEL HEADING" 

.H 2 "Secxmd-level heading" 

.H 3 "Third-level heading" 

.H 1 "ANCXIHER FIRST-LEVEL HEADINS" 

.H 2 "Amther secx3nd-level heading" 

.H 3 "Anotiier third-level heading" 

.H 4 "Pourth-level heading" 

.H 3 "Still anotiier third-level heading" 

.H 5 "Fifth-level heading" 
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produces output like this: 

1. FIRST-LEVEL HEADING 
1.1 Second-level heading 
1.1.1 Third-level heading 

2. ANOTHER FIRST-LEVEL HEADING 
2.1 Another second-level heading 

2.1.1 Another third-level heading 
2.1.1.1 Fourth-level heading 

2.1.2 Still another third-level heading 
2.1.2,0.1 Fifth-level heading 

Enclose the argument in double quotes if the heading contains more 
than one word or contains spaces. One word of heading-text does not 
require quotes. 

In the example above, using a fifth-level heading immediately after a 
third-level heading makes the value of level 4 become zero. Unless you 
conform to the hierarchy of headings (using a second-level heading after a 
first-level heading, and so on), you might obtain results that you do not 
want. 

The heading-suffix argument may be used for footnote marks that should 
not appear with heading text in the table of contents {5.4}, For example, 

.H 1 "TOE UNIX OPERATING SYSTEM" ♦ 
.FS ♦ 

TradenBTk of ATSlT Bell Laboratories. 
.FE 

Do not use \*F as the heading suffix. If you do, a number does not appear 
in the heading as you expect (the string \*F will) and the footnote number- 
ing goes awry. 
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There is no need for a .P macro {3.1) immediately after .H (or .HU, see 
below) because the .H macro performs the spacing and indentation func- 
tions of the .P macro. If you do use .P after .H, mm ignores it. However, it 
is good practice to start every paragraph of a document with a .P macro. 
Later, if you take headings out of your file, paragraphs remain intact. 

The effect of .H on line spacing and the font of the heading-text varies 
according to the level argument. Here is the default effect of each level. 

.H 1 heading-text 

Produces an underlined (italicized) font heading fol- 
lowed by a single blank line. The text after the 
heading-text begins on a new line and indents accord- 
ing to the current paragraph type. 

.H n heading-text 

Produces an underlined (italicized) heading followed 
by two spaces (3 < « < 7). The following text 
begins on the same line, that is, these are run-in 
headings. 

Appropriate numbering and spacing occur even if you omit the heading-text 
argument from a .H macro call. 

3.5.1. Unnumbered Section Headings (.HU) 

To produce an unnumbered heading, type .HU heading-text. The ,HU 
macro is a special case of .H; it acts the same way as .H except that no head- 
ing mark is printed. To preserve the hierarchical structure of headings 
when you intermix .H and .HU calls, .HU produces headings at level 2 by 
default. You may change this default value by changing the value of a the 
number register Hu. Whatever value you give Hu becomes the heading 
level for .HU. Thus, in the normal case, the only difference between 

.HQ *'i4n unnumbered heading" 

and 

•H 2 'M second-level heading"" 
is that the latter prints the heading mark: 
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An rnmumbered heeiding 

2.2 A second-level heading 

By default both macros have the effect of incrementing the numbering 
counter for level 2 and resetting to zero the counters for levels 3 through 7. 
For example, 

1. laiis is a first-level headiiig 

1,1 A seoooxl-level heading 

1.1.1 A third-level heading 

An unnunibered heading 

1.2.1 A third-level heading (note that level 2 has increnaented) 

3.5.2. Altering the Appearance of Section Headings 

You can change the appearance of headings easily by setting certain 
registers and strings at the beginning of the document input text file. This 
permits quick alteration of a document's style because this style-control 
information is concentrated in a few lines rather than being distributed 
throughout the document. 
3.5.2.1. Prespacing and Page Ejection 

A first-level heading, produced by .H 1, normally has two blank lines 
(one vertical space) preceding it. One blank line (one-half vertical space) 
precedes all other headings. You may force every first-level heading to the 
top of a new page by inserting .nr Ej 1 at the beginning of the document 
input text file. Make long documents more manageable by starting each 
section on a new page. Setting the Ej register to a higher value causes the 
same effect for headings up to that level, that is, a page eject occurs if the 
heading level is less than or equal to the Ej value. 
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3.5.2.2. Spacing after Section Headings 

Three registers control the appearance of text immediately following a 
.H call. The registers are Hb (heading break level), Hs (heading space 
level), and Hi (post-heading indent). 

■ If the heading level is less than or equal to Hb, a line break 
(1.4.1) occurs after the heading. 

■ If the heading level is less than or equal to Hs, mm inserts a 
blank line (one-half vertical space) after the heading. 

■ If a heading level is greater than Hb and also greater than Hs, 
then the heading (if any) is immediately followed by text on the 
same line. 

These registers permit you to separate headings from the text in a con- 
sistent way throughout a document and allow you to alter easily white 
space and heading emphasis. The default value for Hb and Hs is 2. 

For any stand-alone heading (a heading on a line by itself) the Hi 
number register controls alignment of the next line of output, 

■ If Hi is 0, text is left-justified. 

■ If Hi is 1 (the default value), mm indents text according to the 
paragraph type as specified by the Pt register {3.1.1}. 

■ If Hi is 2, mm indents text to line up with the first word of the 
heading itself so that the heading number stands out more 
clearly. 

To cause a blank line (one-half vertical space) to appear after the first 
three heading levels, to have no run-in headings, and to force the text fol- 
lowing all headings to be left-justified (regardless of the value of Pt), you 
should put the following line in the parameter setting segment: 

.nr Hs 3 
.nr Hb 7 
.nr Hi 
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3.5.2.3. Centered Section Headings (He) 

Use the He register to obtain centered headings. A heading is centered 
if its level argument is less than or equal to He and if it is also a stand-alone 
heading (3.5.2.2). For example, 

•nr He 1 
.H 1 UNIX 

.H 2 "/plication Packages" 
.H 2 Languages 

produces 

2. UNIX 

1.1 Application Packages 

1.2 Languages 

The He register is initially set to (no centered headings). 

3.5.2.4. Bold, italic, and Underlined Headings 

3.5.2.4.1. Control by Level. 

Any heading that is underlined by the nroff formatter is italicized by 
the troff formatter. The string HF (heading font) contains seven codes that 
specify fonts for heading levels 1 through 7. Legal codes, code interpreta- 
tions, and defaults for HF codes are shown below: 



Formatter 


HF 


Default 


1 


2 


3 


HF 


nroff 
troff 


no underline 
roman 


underline 
italic 


bold 
bold 


2222222 
2222222 



Figure 6: The HF String 



Thus, all levels are underlined by the nroff formatter and italicized by 
the troff formatter. You may reset HF as desired. Any value omitted from 
the right end of the list is assumed to be a 1. The following request would 
result in five bold levels and two underlined (italic) levels: 
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.clsHF3333322 



3.5.2.4.2. nrolf Underlining Style. 

The nroff formatter underlines in either of two styles: 

■ The normal style (.ul request) is to underline only letters and 
digits. 

■ The continuous style (.cu request) underlines all characters 
including spaces. 

By default, mm attempts to use the continuous style on any heading 
that is to be underlined and is short enough to fit on a single line. If a 
heading is to be underlined but is longer than a single line, the heading is 
underlined in the normal style. 

All underlining of headings can be forced to the normal style by using 
the -rUl flag when invoking the nroff formatter {8.4). 

3.5.2.5. Section Heading Point Sizes (HP) 

You may specify the desired point size for each heading level with the 
HP string (for use with the troff formatter only). 

.ds HP [psl] [ps2] [ps3] [ps4] [ps5] [ps6] [p$7] 

By default, mm prints the text of headings (.H and .HU) in the same 
point size as the body except that bold stand-alone headings are printed in a 
size one point smaller than the body. You can specify the string HP, which 
is similar to the string HF, to contain up to seven values, corresponding to 
the seven levels of headings. For example, 

.ds HP 12 12 10 10 10 10 10 

specifies that the first and second level headings are to be printed in 12- 
point type with the remainder printed in 10-point. Specified values may 
also be relative point-size changes, for example, 

.ds HP +2 +2 -1 -1 
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If you specify absolute point sizes, then absolute sizes are used regard- 
less of the point size of the body of the document. If relative point sizes 
are specified, then point sizes for headings are relative to the point size of 
the body even if the latter is changed. 

Null or zero values imply that the default size is used for the 
corresponding heading level. Only the point size of the headings is 
affected. Specifying a large point size without providing increased vertical 
spacing (via .HX and /or .HZ (3.5.4)) may cause overprinting. 
3.5.2.6. Marking Styles Numerals and Concatenation (.HM) 

The registers named HI through H7 are used as counters for the seven 
levels of headings. Register values are normally printed using Arabic 
numerals. The .HM macro (heading mark style) allows this choice to be 
overridden thus providing "outline" and other document styles: 

.HM [argl] ... [arg7] 

This macro can have up to seven arguments; each argument is a string indi- 
cating the type of marking to be used. Legal arguments and their meanings 
are 



Argument 


Meaning 


1 


Arabic (default for all levels) 


0001 


Arabic with enough leading zeroes 




to get the specified number of digits 


A 


Upper-case alphabetic 


a 


Lower-case alphabetic 


I 


Upper-case roman 


i 


Lower-case roman 


omitted 


Interpreted as 1 (Arabic) 


illegal 


No effect 



By default, the complete heading mark for a given level is built by con- 
catenating the mark for that level to the right of all marks for all levels of 
higher value. To inhibit the concatenation of heading level marks, that is, 
to obtain just the current level mark followed by a period, the heading mark 
type register (Ht) is set to 1. For example, a commonly used "outline" style 
is obtained by: 
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.HM I A 1 a i 
.nr Ht 1 



3.5.3. Headings and Table of Contents (CI) 

Automatically collect the text of headings and their corresponding page 
numbers for a table of contents by doing the following: 

■ Specify in the contents level register, CI what level headings 
you want to save 

■ Call the .TC macro {5.4} at the end of the document. 

mm saves any heading whose level is less than or equal to the value of 
the CI register and later displays it in the table of contents. The first two 
levels of headings are saved if you use .TC without putting a value in CI 
(that is, CI by default contains the value 2). 

Because of the way headings are saved, it is possible to exceed the 
formatter's storage capacity, particularly when saving many levels of many 
headings, while also processing displays {3.6} and footnotes {3.3}. if this 
happens, the "Out of temp file space" formatter error message appears (see 
Appendix D); the only remedy is to save fewer levels and /or to have fewer 
words in the heading text. 

3.5.4. Section Headings and User Exit Macros 

The .HX, .HY, and .HZ macros are the means by which you obtain a 
final level of control over the section heading mechanism: 

•HX dlevel rlevel heading-text 
.Hy dlevel rlevel heading-text 
.HZ dlevel rlevel heading-text 

These macros are not defined by mm; they are intended to be defined by 
you. The .H macro call invokes .HX shortly before it prints the heading 
text; it calls .HZ as its last action. After .HX is invoked, the size of the 
heading is calculated. This processing causes certain features that may have 
been included in .HX, such as .ti for temporary indent, to be lost. After the 
size calculation, .HY is called so that you may redefine these features. All 
default actions occur if these macros are not defined. If .HX, .HY, or .HZ 
are defined by you, user-supplied definition is interpreted at the appropriate 
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point. These macros can therefore influence handling of all headings 
because the .HU macro is actually a special case of the .H macro. 

If you originally invoked the .H macro, then the derived level argument 
(dlevel) and the real level argument (rlevel) are both equal to the level given 
in the M invocation. If you originally invoked the .HU macro {3.5.1}, dlevel 
is equal to the contents of register Hu, and rlevel is 0. In both cases, 
heading'text is the text of the original invocation. 

By the time .H calls .HX, it has already incremented the heading 
counter of the specified level {3.5.2.6}, produced blank lines (vertical spaces) 
to precede the heading {3.5.2.1}, and accumulated the "heading mark," that 
is, the string of digits, letters, and periods needed for a numbered heading. 

When .H calls .HX, you may reference all mm registers and strings, as 
well as the following: 

string }0 If you make rlevel non-zero, this string contains the "head- 
ing mark." Two unpaddable spaces (to separate the mark 
from the heading) have been appended to this string. 

If rlevel is 0, this string is null. If string }0 is null, you 
omit the heading mark in the table of contents produced 
with the .TC macro. 

register This register shows the type of spacing that is to follow 
the heading {3.5.2.2}. 

A value of means that the heading is run-in. A value of 
1 means a break (but no blank line) is to follow the head- 
ing. A value of 2 means that a blank line (one-half vertical 
space) is to follow the heading. 

string }2 If "register ;0" is 0, this string contains two unpaddable 
spaces that will be used to separate the (run-in) heading 
from the following text. 

If "register ;0" is non-zero, this string is null. 

register ;3 This register contains an adjustment factor for a .ne request 
issued before the heading is actually printed. On entry to 
•HX, it has the value 3 if dlevel equals 1, and 1 otherwise. 
The .ne request is for the following number of lines: the 
contents of the "register ;0" taken as blank lines (halves of 
vertical space) plus the contents of "register ;3" as blank 
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lines (halves of vertical space) plus the number of lines of 
the heading. 

You may alter the values of }0, ]2, and ;3 within .HX. The following are 
examples of actions that might be performed by defining .HX to include the 
lines shown: 

■ Change first-level heading mark from format n. to n.O: 
.if \\$1=1 .ds }0 \\n(H1.0\<sp>\<sp> 

(where <sp> stands for a space) 

■ Separate run-in heading from the text with a period and two 
unpaddable spaces: 

.if \\n(;0=0 .ds }2 .\<sp>\<sp> 

■ Ensure that at least 15 lines are left on the page before printing 
a first-level heading: 

.if \\$1=1 .nr ;3 (15-\\n(;0 

■ Add three additional blank lines before each first-level heading: 
.if \\$1=1 ,sp 3 

■ Indent level 3 run-in headings by five spaces: 

.if \\$1=3 .ti 5n If temporary strings or macros are used within .HX, their 
names should be chosen with care {6.10.1}. 

When .H calls the .HY macro after the .ne is issued, certain features 
requested in .HX must be repeated. For example, 

.de W£ 

.if \\$1=3 .ti 5n 



The .HZ macro is called at the end of .H to control actions after the 
heading is produced. In a large document, sections may correspond to 
chapters of a book, and you may want to change a page header or footer, for 
example: 

.de HZ 

.if \\$1=1 .PF "Sectiai \\$3" 
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3.6. Displays 

Displays are blocks of text that you want kept together, not split across 
pages, mm provides two styles of displays: static and floating. 

A static display appears in the same relative position in the output text 
as it does in the input text. This may result in extra white space at the bot- 
tom of the page if the display is too big to fit there. 

A floating display **floats" through the input text to the top of the next 
page if there is not enough room for it on the current page. Input text that 
follows a floating display may precede it in the output text. 

By default, a display is processed with line-filling turned off, with 
single-spacing, and not indented from the exiting margins. Do not nest 
displays and footnotes, in any combination. Do not put headings within 
displays or footnotes. 

3.6.1. Static Displays (.DS, .DE) 

A static display is delimited by the .OS and .DE macro pair. 

.DS [format [fill [rindent] ] ] 

Text 

.DE 

With no arguments, .DS accepts lines of text exactly as typed (line-filling 
off) and will not indent lines from the prevailing left margin or from the 
right margin. 

The format argument is an integer or letter you use to control the inden- 
tation and centering of displays. The fill argument is an integer or letter. 
These arguments can have the following meanings: 
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Format 


Meaning 


nil 


no indent 


or L 


no indent 


1 or I 


indent by standard amount 


2orC 


center each line 


3orCB 


center as a block 


none 


no indent 


Fill 


Meaning 


nti 


line-filling off 


OorN 


line-filling off 


1 orF 


line-filling on 


none 


line-filling off 



Figure 7: Arguments to the .DS Macro 



The rindent argument is the number of characters that the line length 
should be decreased, that is, an indentation from the right margin. 

The default static display indentation wth ,DS 1 or .DS I is five spaces, 
but you can change it by changing the value in the number register Si. By 
default, then, text of an indented display aligns with the first line of 
indented paragraphs, unless you also change the value contained in Pi {3.1} . 
These two number registers are independent of one another. 

The display format argument value 3 (or CB) centers (horizontally) the 
entire display as a block (as opposed to .DS 2 and .DF 2 that center each 
line individually). All collected lines are left justified, and the display is 
centered based on width of the longest line. By default, a blank line is 
placed before and after static and floating displays. You can prevent this by 
setting the number register Ds to 0. 

The following example shows usage of all three arguments for static 
displays. The input 
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.DS I F 5 

We the people of the United States, 

in order to form a more perfect union, 

establish justice, ensure domestic trancjoillity, 

provide for the oonman defense, 

and secure the blessings of liberty to 

ourselves and our posterity, 

do ordain and establish this Constitution to the 

United States of /America. 

.DE 

produces 

We the people of the United States, in order to form a 
more perfect union, establish justice, ensure domestic tranquil- 
lity, provide for the common defense, and secure the blessings of 
liberty to ourselves and our posterity, do ordain and establish 
this Constitution to the United States of America. 

This block of text is indented five ems from the current left margin, filled, 
and indented five spaces from the right margin. 

3.6.2. Floating Displays (.DF, .DE) 

Delimit a floating display with the macro pair .DF and .DE. 

.DF [format [fill [rindent] ] ] 

Text 

.DE 

Arguments to .DF have the same meanings as they do to .DS except when 
they concern format. With floating displays, the formatter calculates inden- 
tation and centering with respect to the initial left margin because the pre- 
vailing indent may change between the time when the formatter first reads 
the floating display and when the display is printed. One blank line occurs 
before and after a floating display. 

When the formatter encounters a floating display, it processes and 
places the display onto a queue waiting to be output. The formatter 
removes displays from the queue and prints them in the order entered, 
which is th'3 order they appeared in the input file. If a new floating display 
is encountered and the queue of displays is empty, the new display is a can- 
didate for immediate output on the current page. 
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As long as the display queue contains one or more displays, the for- 
matter automatically enters new displays there, rather than putting them 
out. When the formatter puts out a display, it also removes it from the 
queue. 

When the formatter reaches the end of a section (using section-page 
numbering) or the end of a document, it automatically removes all displays 
from the queue, putting them out. This occurs before the formatter 
processes an .SG macro (S.l). 

A display will fit on the current page if there is enough room to contain 
the entire display or if the display is longer than one page in length and 
less than half of the current page has been used. 

You may exercise precise control over the positioning of floating 
displays on output with two number registers, De and Df (see below). 
Immediate output of the display queue is governed by size of display and 
the setting of the Df register code. The De register code controls whether 
text will appear on the current page after a floating display has been pro- 
duced. 

The De and Df number register code settings and actions are as follows: 

De register: 

Code Action 

No special action occurs (also the default condition). 

1 A page eject always follows the output of each floating display, so 
only one floating display appears on a page and no text follows it. 

For any other code, the action performed is the same as for code 1. 

Df register: 

Code Action 

Floating displays are not output until end of section (when 
section-page numbering) or end of document. 

1 Output new floating display on current page if there is space; oth- 
erwise, hold it until end of section or document. 
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2 Output exactly one floating display from queue to the top of a new 
page or column (when in 2-column mode). 

3 Output one floating display on current page if there is space; oth- 
erwise, output to the top of a new page or column. 

4 Output as many displays as will fit (at least one) starting at the top 
of a new page or column. If De is set to 1, each display is fol- 
lowed by a page eject, causing a new top of page to be reached 
where at least one more display is output. 

5 Output a new floating display on the current page if there is room 
(default condition). Output as many displays (but at least one) as 
will fit on the page starting at the top of a new page or column. If 
De is set to 1, each display is followed by a page eject causing a 
new top of page to be reached where at least one more display is 
output. 

For any code greater than 5, the action performed is the same as for code 5. 

You may also use the .WC macro {6.7} to control handling of displays in 
double-column mode and to control the break in text before floating 
displays. 

3.7. Tables (using tbl) 

.TS [H] 

global options; 
format section, 
title lines 
[.Til [N]] 
Data 
•TE 

The macro pair TS (table start) and .TE (table end) delimits text to be 
examined by tbl and sets proper spacing around the table. The display 
function (.DS and ,DE) and the tbl delimiting function are independent. 
To keep together blocks that contain any mixture of tables, equations, filled 
text, unfilled text, and caption lines, enclose the .TS/.TE block within a 
display (.DS/.DE) if the table is less than a page long. You may enclose 
floating tables inside floating displays (.DF/.DE). 
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mm formats headings for tables that extend over several pages. If a 
table heading is needed for each page of a multi-page table, the H argument 
should be specified to the .TS macro as above. Following the options and 
format information, table title is typed on as many lines as required and is 
followed by the TH macro. The .TH macro must occur when .TS H is used 
for a multi-page table. This is not a feature of tbl but of the definitions pro- 
vided by the mm macro package. 

The .TH (table header) macro may take as an argument the letter N. 
This argument causes the table header to be printed only if it is the first 
table header on the page. Use this option when it is necessary to build long 
tables from smaller .TS H/.TE segments. For example, 

.TS H 

Global options; 

Format section. 

Title lines 

.TO 

Data 

.TE 

.TS H 

Global options; 
Format section. 
Title lines 
.TO N 
Data 
.TE 

causes the table heading to appear at the top of the first table segment and 
no heading to appear at the top of the second segment when both appear 
on the same page. However, the heading still appears at the top of each 
page that the table continues onto. Use this feature when a single table 
must be broken into segments because of table complexity (for example, too 
many blocks of filled text). If each segment had its own .TS H/.TH 
sequence, it would have its own header. However, if each table segment 
after the first uses .TS H/.TH N, the table header will appear only at the 
beginning of the table and the top of each new page or column that the 
table continues onto. 
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For the nroff formatter, you may use the -e option [— E for mm {8.l}] 
for terminals that are capable of finer printing resolution. This causes better 
alignment of features such as the lines forming the corner of a box. The -e 
option is not effective with col. 



3.8. Equations (using eqn) 

.DS 

.BQ [label] 
Equation($) input 

The programs neqn and eqn expect to use the .EQ (equation start) and 
.EN (equation end) macros as delimiters in the same way that tbl uses .TS 
and .TE; however, .EQ and .EN must occur inside a .DS/.DE pair. There is 
an exception to this rule — if .EQ and .EN are used to specify only the del- 
imiters for in-line equations or to specify eqn /neqn defines, the .DS and 
.DE macros must not be used; otherwise, extra blank lines will appear in the 
output. 

The .EQ macro takes an argument that will be used as a label for the 
equation. By default, the label will appear at the right margin in the "verti- 
cal center** of the general equation. The Eq register may be set to 1 to 
change labeling to the left margin. 

The equation will be centered for centered displays; otherwise, the 
equation will be adjusted to the opposite margin from the label. 



3.9. Figure, Tabie, Equation, and Exhibit Tities (.FG, 
.TB, .EC, .EX) 

You may use the .FG (figure title), .TB (table title), .EC (equation cap- 
tion), and .EX (exhibit caption) macros inside .DS/.DE pairs to number 
figures, tables, and equations automatically, and give them titles. 
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.FS [title [override [flag] ] ] 

.TB [title [override [flag] ] ] 

.EC [title [override [flag] ] ] 

•EX [title [override [flag] ] ] 

These macros use registers Fg, Tb, Ec, and Ex, respectively (see section 8.4 
on — rN5 to reset counters in sections). For example, 

.PS "This is a Figure Title" 

yields 

Figure 1, TMs is a Figure Title 

The .TB macro replaces "Figure" with "TABLE/ the .EC macro replaces 
"Figure" with "Equation," and the .EX macro replaces "Figure" with "Exhibit." 
The output title is centered if it can fit on a single line; otherwise, all lines 
but the first are indented to line up with the first character of the title. 
Change the format of the numbers using the .af request of the formatter. 
By setting the Of register to 1, you may change the format of the caption 
from 

Figure 1. Title 

to 

Figure 1 - Title 

Use the override argument to change normal numbering. If you omit the 
flag argument or use an argument of 0, override is used as a prefix to the 
number; if the flag argument is 1, override becomes a suffix; and if the flag 
argument is 2, override replaces the number. If -rN5 {8.4} is given, 
"section-figure" numbering is set automatically and user-specified override 
argument is ignored. 

As a matter of formatting style, you might want to place table headings 
above the text of tables, and put figure, equation, and exhibit titles below 
corresponding figures and equations. 

You obtain a List of Figures, List of Tables, List of Exhibits, and List of 
Equations after mm prints the Table of Contents if the number registers Lf, 
Lt, Lx and Le (respectively) are set to 1. By default, all but Le are set to 1 by 
default. You can change the titles of these lists by redefining the following 
strings, which are presented here with their default values: 
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.ds Lf LIST OF FIGURES 
.ds Lt LIST OF TAHfiKS 
.ds Lx LIST OF EXHIBITS 
.ds Le LIST OF EQUATIONS 



mm; TECHNICAL DISCUSSION 55 



4. Formatting the Beginning of a Document 



Two specific styles of documents are available with mm: formal 
memorandum style, which includes formats for memoranda, released papers 
and external letters, and business letter style. 



4.1. Formal Memorandum Style 

The mm formal memorandum style allows three document types: the 
memorandum, the released paper and the external letter. Commonly, peo- 
ple who write formal memoranda put certain information at the beginning 
of the document (the date, title, case numbers, authors, and so on) or at the 
end of the document (the signature line and a list of the document's reci- 
pients), and put it nowhere else. You specify these beginning and end 
items the same way for each formal memorandum type. Their formatted 
appearance depends on which type you choose with the .MT macro. (See 
"Appendix G" for an example of a formal memorandum.) 

4.1.1. Choosing a Formal Memorandum Type (.MT) 

This is how you use .MT: 

.MT [argument [addressee] ] 

An argument specifies a particular formal memorandum type. Legal values 
for the argument are as follows: 
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Argument 


Type 


Value 




itiexnorandutn 


no memoranaum type printea 





mpmorandum 


no memorandum tvoe orinted 


none 


memorandum 


MEMORANDUM FOR FILE 


1 


memorandum 


MEMORANDUM FOR FILE 


2 


memorandum 


PROGRAMMER'S NOTES 


3 


memorandum 


ENGINEER'S NOTES 


4 


released-paper 


released-paper style 


5 


external-letter 


external-letter style 




memorandum 


string (enclosed in quotes) 



Figure 8: Arguments to the .MT Macro 



The formal memorandum style produces a standard mast at the top of 
the first page of your document. The following input lines produce the 
next mast (and those that follow it). Put these lines immediately after the 
parameter setting segment of your document: 

.ND "September 28, 1984" 
.TL 

Document Production Coordinator 
.AU "John Smith" JS XF 5414 6398 7-123 
•AF "Business Ccmputer Sjrstems, Inc*" 
•MP n (where n is a legal argument to .MT) 

First, consider the memorandum type (here, .MX). 

Business Computer Systems, Inc. 

subject: Document Production date: September 28, 1984 

Coordinator 

from: John Smith 
XF 5414 
x6398 7-123 

If you give .MT any argument other than 4 or 5, you obtain, a few lines 
after the last line of author information, the value of value in the preceding 
table. 
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There are two alternatives to the memorandum type. To obtain the 
released-paper style, use .MX 4, which produces a different mast; 

Document Production Coordinator 

John Smith 
Business Computer Systems, Inc. 

With the external-letter style (.MX 5), mm prints only the title (without the 
word "subject:") and the date in the opposite left and right corners, respec- 
tively, of the top of the first page. 

Document Production 
Coordinator 



September 28, 1984 

Specify the addressee of a memo, released paper or letter with the 
second argument to .MX. This argument may be any words you choose. 
Providing the addressee causes the name you've specified and the page 
number to replace the normal page header (page headers will be discussed 
below) on the second and succeeding pages of a memo. 

.m 1 "Michael Staith" 

You may not use the addressee argument when the .MX type equals 4. 
If you try, output will cease after the first page. 

4.1.2. XM Numbers 

If the memorandum is an AT&T technical memorandum, TM numbers 
are supplied via the .XM macro. 

.TM [number] ... 

Up to nine numbers may be specified. For example, 

••m 7654321 77777777 

mm ignores this macro call in the released-paper and external-letter styles 
{4.4.1}. 
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4.1.3. Changing the Date (.ND) 

By default, the current date appears in the "date" part of a memorandum 
or in the right corner of an external letter. You may override the current 
date using the .ND macro. 

.ND new date 

4.1.4. Giving the Memorandum a Title (TL) 

The .TL macro gives your formatted document a title. To use ,TL, type: 

.TL [charging-case rtumber(s) [filing-case number(s)] ] 
Text 

.AU (or another macro) 

AT&T Bell Laboratories uses arguments to the .TL macro to specify the 
charging-case number(s) and filing-case number(s), 

■ The charging-case number stands for an account to which a 
person's time is charged. Enter multiple charging-case numbers 
as "subarguments" by separating each from the previous with 
a comma and a space, and enclosing the entire argument 
within double quotes (see example below). 

■ The filing-case number describes where the memorandum is to 
be filed. Enter multiple filing-case numbers the same way you 
enter charging-case numbers (see example below). 

Here is an example of specifying more than one charging-case number and 
filing-case number: 

.TL "12345, 67890" "987654321, 987654322" 
Etocument Production Oxardinatxar 

Those numbers will appear after the title like this (except for released paper 
style, when they do not appear at all): 

Document Production 
Coordinator 

Qiarge Case 12345 , 67890 

File Case 987654321, 987654322 
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The title of the memorandum follows the .TL macro. You may use the 
.br request to break the title into several lines 

.TL 12345 

Document Production 
.br 

Coardinator for the 
.br 

Technical Writing Staff 

4.1.5. Specifying the Author (.AU) 

Use .AU to specify the author of your memo or paper: 

.AU name Unitials [loc Idept [ext [room [arg [arg [arg]]]]]]]] 
.TL 12345 

Document Production 
.br 

Coordiiiator for the 
.br 

Technical Writing Staff 

In the "from:" portion of a formatted memorandum, location and depart- 
ment number follows the author's name on one line and room number and 
extension number follow it on the next line. The "x" for the extension is 
added automatically: 

from: John Smith 
XF 5414 
7-123 X6398 
machine 5Ijjs 

For the memorandum type, you type information that describes an 
author after the .AU macro as arguments. This information includes: 

■ name (for example, John Smith) 

■ initials (for example, JJS) 

■ location (XF) 
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■ department (5414) 

■ telephone extension (6398) 

■ room (7-123) 

■ one, two or three additional arguments (for example, 
machine_5!jjs) 

The first six arguments must appear in the order given, that is, the author's 
name must be typed before the initials, which must be typed before the 
location, and so on. By default, these arguments are ignored for the 
released paper style and the external letter style. If you want to leave any 
of these arguments blank, put a null argument at the appropriate place. 

If you want to suppress printing the location, department number, 
extension number, room number and later arguments, set the number regis- 
ter Au to 0; the default value is 1. 

If a memorandum has more than one author, use a separate .AU macro 
for each author, for example, 

.AU "John smith" JJS XF 5414 6398 7-123 inachine_5l jjs 
.AU "John Foley" JJP XF 5415 6666 7-321 machine^e 1 jf 

produces 

from: John Smith 
XF 5414 
7-123 X6398 
machine_5 I j js 

John Foley 
XF 5415 
7-321 X6666 
machine_6 1 jf 

4.1.6. Specifying the Author's Title (.AT) 

Specify the author's title with the .AT macro. 
,AT title ... 
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.AT must immediately follow .AU for the given author. For example, 

.AU "John anith" JJS XF 5414 6398 7-123 
.AT Supervisor "Technical Writing Staff" 

produces the following output at the signature block: 

Jcthn Snoith 
Supervisor 

Technical Writing Staff 

You may give .AT up to nine arguments. Each argument will appear in 
the signature block (at the end of the memorandum, which is discussed 
below) on a separate line following the signer's name. If you need a long 
title, surround phrases in double quotes, turning several words into single 
arguments. 

4.1.7. Specifying the Author's Firm (.AF) 

Supply the name of your firm with .AF. 

.AF "name of the firm*' 

Use .AF before .AU to avoid a formatting error. If you use .MT 4, your firm 
name appears after the author's name. For example, 

•AF "Business Conputer Systems, Inc." 

puts "^Business Computer Systems, Inc." in bold letters in the upper right 
hand corner of the first page of your memo. If you specify .MT 4, "Business 
Computer Systems, Inc." appears centered and double spaced from the 
author's name. 



If you do not supply a name with .AF, "AT&T Bell Laboratories" appears as 
the name of your firm unless your system administrator edits strings.mm 
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4.1.8. Calling Beginning Formal Memorandum Macros in the Correct 
Order 

If you use the macros described thus far, you must call them in the fol- 
lowing order to avoid a formatting error: 
.ND new date 

.TL [charging-case number(s) [filing-case number($)] ] 
Text 

•AF "name of the firm" 

.AU Name [initials [loc [dept [ext [room [arg [arg [arg]]]]]]]] 
.MT [type [addressee] ] 

•AF "Business Conputer Systems, Inc." 

The only required macros for a memorandum, released paper or external 
letter are .TL, .AU, and .MT. 



4.2. Other Beginning Macros 

4.2.1. Abstract (.AS, .AE) 

If a formal memorandum has an abstract, delimit the text of the abstract 
with the .AS (abstract start) and .AE (abstract end) macro pair. 

.AS [arg [indent] ] 
Text of abstract 
.AE 

Abstracts are printed on page one of a document and /or on its cover sheet. 
There are three types of cover sheets: 

■ Released paper 

■ Memorandum 

■ Memorandum for file (also used for engineer's notes, 
memoranda for record, and so on) 

Cover sheets for released papers and memoranda are obtained by invok- 
ing the .CS macro. 
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With the released-paper type (argument to the .MT macro is 4) and with 
the memorandum type, if the first argument of .AS is 

— Abstract prints on page 1 and on the cover sheet (if any). 

1 - Abstract appears only on the cover sheet (if any). 

With the memorandum for file type and in all other documents (other 
than external letters) if the first argument of .AS is: 

- Abstract appears on page 1 and no cover sheet prints. 

2 - Abstract appears only on the cover sheet that will be produced 

automatically (that is, without invoking the .CS macro). 

It is not possible to get either an abstract or a cover sheet with an exter- 
nal letter (first argument of the .MT macro is 5). 

Notations such as a "Copy to" list are allowed on memorandum for file 
cover sheets; the .NS and .NE macros must appear after the .AS 2 and .AE 
macros. Headings and displays are not permitted within an abstract. 

The abstract is printed with ordinary text margins; an indentation to be 
used for both margins can be specified as the second argument of .AS. 
Values that specify indentation must be unsealed and are treated as "charac- 
ter positions/' that is, as the number of ens. 

4.2.2. Other Keywords (.OK) 

.OK keyword [...] 

Topical keywords should be specified on a technical memorandum cover 
sheet. You may specify up to nine such keywords or keyword phrases as 
arguments to the .OK macro; if any keyword contains spaces, you must 
enclose them in double quotes. 

4.2.3. Bottom Block (.BS, .BE) 

Specify lines of text to be printed at the bottom of each page after the 
footnotes (if any) but before the page footer with the bottom block macro 
pair .BS/.BE. 
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.BS 

Text 
.BE 

The bottom block should occur before the use of any footnotes (3.3) or mac- 
ros that define the memorandum style {4.1.4). Otherwise, an interaction 
between this macro pair and another macro that redefines the appearance of 
the bottom of the page may cause you problems. 

Remove the bottom block by specifying an empty block, as shown 
below: 

•BS 
•BE 

The bottom block appears on the table of contents, text pages, and the cover 
sheet for memorandum for file, but it does not appear on the technical 
memorandum or released-paper cover sheets. 



4.3. Proprietary Marking Macro (.PM) 

The .PM (proprietary marking) macro appends to the page footer a 
proprietary disclaimer. 

.PM [code] 

The argument is selected from among the following (note that argu- 
ments formerly used with DOCUMENTER'S WORKBENCH Software 1.0 are 
included): 
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Current 
Arg 


Former 
Arg 


Disclaimer 
Message 


PMl 


BP,N,P, 
BPN 


AT&T BELL LABORATORIES • PROPRIETARY 
Use pursuant to G.E.L 2.2 


PM2 
CA 


none 


THIS DOCUMENT CONTAINS PROPRIETARY INFORMATION OF 
AT&T AND IS NOT TO BE DISCLOSED OR USED EXCEPT IN 
ACCORDANCE WITH APPLICABLE CONTRACTS OR AGREEMENTS. 


PM3 
CP 


none 


SEE PROPRIETARY NOTICE ON COVER PAGE 


PM4 


BPP,BR 


AT&T BELL LABORATORIES - PROPRIETARY (RESTRICTED) 
Solely for authorized persons having a need to know 
pursuant to G.E.L 2.2 


PM5 


ILL 


THIS DOCUMENT CONTAINS PROPRIETARY INFORMATION OF 

AT&T BELL LABORATORIES AND IS NOT TO BE DISCLOSED, 

REPRODUCED, OR PUBLISHED WITHOUT WRITTEN CONSENT. 

THIS DOCUMENT MUST BE RENDERED ILLEGIBLE WHEN BEING DISCARDED. 


PM6 


CMI 


CHI 

Not for disclosure to AT^eT Information Systems. 

Subject to FCC separation requirements under Computer Inquiry 11 



Figure 9: Arguments to .PM (Proprietary Markings) 



Use .PM at the beginning of your document, before you use footnotes {3.3} 
or macros that define the memorandum style {4.1.4). Otherwise, an interac- 
tion between this macro and another that redefines the appearance of the 
bottom of the page may cause you problems. 
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These disclaimers are in a form approved for use by the AT&T. Mark- 
ings are underlined. (They are italic in troff.) You may use the CMI mark- 
ing with any other message by two separate .PM requests. For example, 

.FM CI-II 
.FM N 

produces a CI-II and NOTICE mark. 

These proprietary markings are specified in the define file. System 
administrators can change the contents of this define file, strings.mm, to 
match your needs. This file is described in the next section. In cases where 
the disclaimer message for a code argument has been removed the argument 
issues a currently approved disclaimer message. Since the code argument 
may produce a different disclaimer message (a shorter or longer message), 
the page formatting of the document may be affected. 



4.4. Define File Information 

The define file contains pre-defined strings for the .MT and .PM mac- 
ros. Appendix E presents the contents of the file. The file 
/usr/lib/macros/strings.mm contains the define file. Only system adminis- 
trators may change specific string and font information, since only they 
have write permissions for the define file. 



4.5. Business Letter Style 

An alternative to the formal memorandum style is the business letter 
style, which produces four types of business letters: blocked, semiblocked, 
full-blocked, and simplified. (See Appendix H for an example of an mm 
business letter.) 

4.5.1. Letter-Type Macro (.LT) 

The letter-type macro .LT formats a letter in one of four business styles: 
.LT largi 
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.LT accepts one (optional) argument. Arguments and corresponding 
format are as follows: 



Argument 


Format 


none 


blocked 


BL 


blocked 


SB 


semiblocked 


FB 


full-blocked 


SP 


simplified 



XT controls the placement on the page of the output of the subordinate 
macro .LO and the subordinate macro pairs (.lA and .IE, .WA and .WE) 
which differs according to each of the four business letter formats. 

Business letter and formal memorandum macros (.LT and .MT) are 
mutually exclusive. If you specify both .LT and .MT specific macros in a 
single document, nroff /troff attempts to process the file according to the 
first formatting specific macro it encounters, mm ignores .MT-specific mac- 
ros (.2C, .AF, .AS, .AT, .AU, .AV, .CS, .OK, .TC, .TL, .TM) and .MT-specific 
command line parameters (-rAn, -rEn, -rN4) if you use them with .LT; 
conversely, if you use .LT-specific macros (.WA, .WE, .lA, .IE, .LO) with 
.MT, mm ignores them. 

If you use these business letter macros, the macro pairs, .WA-.WE and 
.lA-.IE, and the page formatting macro .LT are required, all other business 
letter macros are optional. 

The .LT macro arguments control paragraph indentation for each of the 
four letter types. If you redefine the Ft and Pi registers, the user specified 
indentations will override. Specification of the Ft and Pi registers must 
occur after specification of the .LT macro. 

■ In the blocked format all lines of text begin at the left margin 
except the date line, return address, closing, and writer's 
identification. These begin at the center of the line. (The center 
of the line is not a fixed point, it is calculated for the current 
line length.) 
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■ The semiblocked format is the same as the blocked format; 
except, the first line of each paragraph is indented five spaces. 

■ In full-blocked format all lines begin at the left margin. There 
are no exceptions. 

■ The simplified format is the same as the full-blocked format; 
except, the salutation is replaced by an all-capital subject line 
and is followed by an additional blank line, the closing is omit- 
ted, and the writer's identification is in all-capital letters on one 
line. 

Table 1 presents a synopsis of the placement of business letter com- 
ponents for the four XT letter formats and lists the macros (which are 
explained in detail below) that you use to format those components. 
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Placement on Page By .LT Argument 



Macro & Function 


BL 


SB 


FB 


SP 


.WA/.WE 

Writer's Address 


Center 


Center 


Left 


Left 


.LO CN [arg] 
Confidential Notation 


Left 


Left 


Left 


Left 


.LO RNIarg] 
Reference Notation 


Center 


Center 


Left 


Left 


.IA/.IE 

Inside Address 


Left 


Left 


Left 


Left 


.LO AT [arg] 
Attention 


Lett 


Left 


Left 


Left 


T 1^ G A F/ttfAl 
tlAJ oA {OTgl 

Salutation 


Left 


Left 


Left 


None 


.LO SJ [arg] 
Subject Line 


Left 


Indented 


Left 


Left 


.? Paragraphs 


Left 


Indented 


Left 


Left 


.FC Closing 


Center 


Center 


Left 


Left 


.SG Signature 


Center 


Center 


Left 


Left 


.NS/.NE 

Copy Notation 


Left 


Left 


Left 


Left 



Figure 10: Arguments to the .LT Macro and their Functions 



There are two possible error conditions for the .LT macro: 

■ If you omit the .LT macro, file processing aborts and an 
appropriate error message prints. 
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■ If mm does not recognize an argument to .LT, the file process- 
ing aborts and an appropriate error message prints. 

4.5.2. Writer's Address Macros (.WA, .WE) 

Use this macro pair to specify the writer (author) of the letter and the 
writer's return address. 

.WA writer-name [title] 

Return address 

.WE 

For exaitple, 

.WA "James Lorrin, Ph.D." Director 

Sumcdt Research Ccxrpany 

38 River Road 

Suninit, New Jersey 07901 

.WE 

If a complete return address is not necessary for the letter (for example, 
if you use printed letterhead stationary) you can specify the writer informa- 
tion alone: 

.WA "James Lorrin, Ph.D." Director 
.WE 

The return address cannot exceed 14 lines. Lines in the return address 
that follow line 14 do not appear on the letter. 

The two arguments specified for the .WA and .WE macro pair, the 
writer-name and the title, provide information used by the .SG macro {5.1}. 
If you do not specify the .SG macro, the writer's name does not appear on 
the letter. 

For the case of multiple writers on a single letter, you may specify only 
one writer return address. The specified writer return address must appear 
with the first writer-name as the first invocation of the .WA/.WE macro 
pair. Later return address specifications do not appear on the letter, 
although any number of additional writer names may be specified. For 
example. 
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.WA "James Larrin, Ri.D." Director 

Suninit Research Conpaxiyr 

38 River Road 

Summit, New Jersey 07901 

.WE 

.WA "John Smith" Supervisor 
.WE 

.WA "Diane Kane" "Technical Si]?]port" 
.WE 



For blocked and semiblocked letter styles the writer return address 
begins on line 12 from the top of the first page and each line begins at the 
center of the line. For the full-blocked and simplified letter styles the 
writer return address begins on line 12 from the top of the page and each 
line begins at the left margin. 



NOTE 



Top of page processing can be controlled directly through nroff. The 
beginning of the printed page is user-defined. See the requests .wh and .ch 
in the "nroff/troff Technical Discussion." 



If you omit either or both of the .WA and .WE macros, the file process- 
ing aborts and an appropriate error message prints. 

4.5.3. Inside Address Macros (.lA^ .IE) 

.lA and .IE are a macro pair you use to specify the addressee and the 
addressee's address. There are two different ways that you can use this 
macro pair: 

.lA 

Text 
.IE 



or 



.lA [addressee-name [title] ] 

Text 

.IE 



For example. 
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• lA 

Fred Staith, Ph.D. 
Columbia University 
116th Street 

New York, New York 10019 
.IE 

or 

.lA "Fred Smith, Ph.D." 
.IE 

For all four letter styles of .LT, the inside address prints on the fifth line 
below the date (if a reference notation or confidential notation appear after 
the date, the inside address prints three lines below the notation) and each 
line begins at the left margin. 

If you omit either or both of the .lA and .IE macros, the file processing 
aborts and an appropriate error message prints. 

4.5.4. Letter-Options Macro (.LO) 

The letter-options macro provides the capability for specifying five com- 
mon business letter components: 

.DO type [arg] 

The .LO macro takes care of placement and spacing of these letter com- 
ponents for each .LT letter format. .LO requires one argument to specify a 
letter component type, and accepts one optional string argument to refine 
its action. 
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Type 



Corresponding Component 



CN 
RN 
AT 
SA 
SJ 



confidential notation 
reference notation 
attention 
salutation 
subject line 



Figure 11: Types Given to XO and their Functions 



4.5.4.1. Confidential Notation (CN) 

The confidential notation shows that a business letter should be read 
only by the person to whom it is addressed. The confidential notation 
appears on the second line below the date line of the letter and begins at 
the left margin for all letter formats. 

If the optional string argument is present the specified string replaces 
the default. For example, 

.LO CN "RESTRICOED" 

The default of CN prints CONFIDENTIAL in upper-case. 

4.5.4.2. Reference Notation (RN) 

The reference notation supplies specific information to be used by the 
addressee. For example, 

.LO BN "Meeting of 1/25" 

The reference note appears two lines below the date line of the letter (or on 
the second line below any notation that follows the date) left aligned with 
the date line for all four letter formats. 

RN provides a common format for including a reference note by print- 
ing the string In reference to: preceding the optional string argument to 
.LO. The format string In reference to: cannot be redefined. There is not a 
default value for the optional argument. 
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4.5.4.3. Attention (AT) 

The attention line directs the letter to the attention of a specific person 
or department. For example, 

.LO AT "Dr. Smith" 

The attention information appears on the second line below the inside 
address of the letter and begins at the left margin. 

AT provides a common format for directing a letter to the attention of a 
specific person by printing the string "ATTENTION:" preceding the 
optional string argument to .LO, The format string "ATTENTION:" cannot 
be redefined. There is not a default value for the optional argument. 

4.5.4.4. Salutation (SA) 

The salutation specifies the letter's opening greeting. For the blocked, 
semiblocked, and full-blocked formats the salutation appears on the second 
line below the inside address (or on the second line below the attention 
line, if used). In the simplified letter format, the salutation is ignored. 

The default of SA prints "To Whom It May Concern:" for the salutation. 
If the optional string argument is present the specified string will replace 
the default. For example, 

.10 SA "Dear Dr. Staith" 

4.5.4.5. Subject Line (SJ) 

The subject line shows what the letter is about. In the blocked and 
full-blocked letter formats the subject line information appears on the 
second line below the salutation and begin at the left margin. For the semi- 
blocked format the subject line appears on the second line below the saluta- 
tion and is indented five spaces. In the simplified letter format the subject 
line information appears in place of the salutation three lines below the 
inside address of the attention line; the salutation, if you use it, is ignored. 

For the blocked, semiblocked, and full-blocked formats, SJ provides a 
common format for indicating what the letter is about by printing the string 
"SUBJECT: preceding the optional string argument to .LO. 

.10 SJ "St3ff Meeting:" 

The format string "SUBJECT: cannot be redefined. There is not a default 
value for the optional argument. 
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For the simplified letter, the subject line string argument prints on the 
third line below the inside address or the attention line (a salutation is 
ignored if used). 

If you specify the .LO macro without an argument or the argument you 
specify is unrecognized, the file processing aborts and an appropriate error 
message prints. 

4.5.5. Multi-page Letters 

The .LT macro controls the format for the first page of the letter. The 
letter macros will not alter the default nroff /troff page processing follow- 
ing the first page of the letter. 

4.5.6. Sequence of Beginning Letter IMacros 

Macros .WA, .WE, .lA, .IE, and .LT must be given in the order listed in 
the following table. .LO can be specified multiple times with different 
argument types. The .LO argument types do not have to be in any specific 
order. All .LO requests must be specified before .LT. 
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,ND new date 

.WA writer's name [title] 

Return address 

Street 

City, State Zip Code 

Text 

.WE 

• lA 

Addressee name 
Title 

Company 
Street 

City, State Zip Code 

Text 

.IE 

.10 type [arg] 

.LT [arg] 

.P 

Text 

.BC 

.SG larg [1] ] 
.NS [arg [1] ] 
Text 
.NE 

If you put nroff /tro£f requests and lines of text before ,LT, you change 
how .LT works. For example, if the first line of a file is a line of text, mm 
processes the file as if you had not specified .LT. 
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5.1. Formal Closing and Signature Line (.FQ .SG) 

If you like, you may make your formal memorandum more formal with 
the .FC macro, which prints "Yours very truly/' as a formal closing. You 
may specify an argument to .FC. to present a different closing. 

The .SG (for "signature line") macro prints the author's name(s) after the 
formal closing, otherwise the author's name appears after the last line of the 
body of the memo. Each printed name begins at the center of the page. 
Three blank lines are left above each name for an author's signature. Use 
.FC before .SG or the formal closing will appear after the signature line. 

Here's how you use .FC and .SG together. You may use either macro by 
itself. 

.PC ["closing argument**] 
,9G [arg [1] ] 

You append a line of reference data including location code (for exam- 
ple, XF), department number (5414) and author's initials (JJS) by typing .SG 

instead of .SG. These data appear after the author's name and before the 
"Copy to" list (which is described below) and look like this: 

XF-5414-JJS 

If you type any other argument after .SG (not ""), that argument is treated as 
the typist's initials and is appended to the reference data. For example, if 
you specify: 

.SG abc 

the following line appears after the author's signature and before the "Copy 
to" list: 

XF-5414-JJS-abc 

If there are several authors and the second argument is given, reference 
data is placed on the signature line of the first author. This reference data 
contains only the location and department number of the first author, even 
though the other authors' initials are printed. Therefore, if there are 
authors from different departments and/or from different locations, the 
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reference data should be supplied manually after calling .SG without argu- 
ments, like this: 

.SG 

XF-5414-JJS 
XF-5415-SJF 

This manually supplied information appears on the signature line of the 
second author. 

For business letter style documents, the .SG macro prints the writer's 
name(s) after the formal closing, if any. Placement of the writer's names(s) 
for the signature block is controlled by the ,LT macro specification (for 
example at the left margin or at the center of the page). The optional argu- 
ments accepted by .SG will not alter the processing of the macro when used 
in conjunction with .LT. 



5.2. Approval Line (.AV) 

Use the .AV macro after the last notation block to generate automati- 
cally a line for the approver's signature and the date. 

.AV approver' s-name [1] 

For example, 

.AV "Itodd Doe" 
produces 

APPROVED: 



Todd Doe Date 

Use the optional second argument to prevent the mark "APPROVED:" from 
appearing above the approval line. 

The .SG and .NS macros format signatures of authors and a list of nota- 
tions, respectively. These macros do not work with released-paper style 
(.MT 4, 4.1.1). 
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5.3. "Copy to" and Other Notations (.NS, .NE) 

Many types of notations (such as a list of attachments or "Copy to" lists) 
may follow signature and reference data. Various notations are obtained 
through the .NS macro, which provides for proper spacing and for breaking 
notations across pages if necessary. You use .NS like this: 

.NS [argument [1] ] 
Names or other notation 
.NE 

If you use the optional second argument, the first argument will be used 
as the entire notation string. Codes for argument and the corresponding 
notations are 



Argument 


Notations 


none 


Copy to 




Copy to 





Copy to 


1 


Copy (with att.) to 


2 


Copy (without att.) to 


3 


Att. 


4 


Atts. 


5 


Enc. 


6 


Encs. 


7 


Under Separate Cover 


8 


Letter to 


9 


Memorandum to 


10 


Copy (with atts.) to 


11 


Copy (without atts.) to 


12 


Abstract Only to 


13 


Complete Memorandum to 


"string** 


Copy (string) to 


**$tring'\ with 2nd arg 


string 



Figure 12: Arguments to the .NS Macro 
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The string, which you may or may not enclose in double quotation 
marks, is placed within parentheses between the words "Copy" and "to" if it 
consists of more than two characters; otherwise, it is ignored. For example, 

.NS "vath att. 1 only" 

generates 

Copy (with att. 1 only) to 

as the notation. 

You may specify more than one notation before the .NE macro because 
a .NS macro stops the preceding notation, if any. For example, 

.NS 4 

Attachment 1-List of branch offices and managers 
Attachment 2-List of regional offices and managers 
.NS 1 

Bill Taylor 

.NS 2 

J, Craven 

A. Greenland 

.NE 

produces 

Atts . 

Attachment 1-List of branch offices and managers 
Attachment 2-List of regional offices and managers 

Copy (with att. ) to 
Bill Taylor 

Copy (without att.) to 
J. Craven 
A. Greenland 

If you use a second argument, the first argument becomes the entire 
notation. For example, 

.NS "Table of (Contents to" 1 

produces 

Table of Contents to 
as the notation. 



mm: TECHNiCAL OiSCUSSION 81 



Formatting the End of a Document 

You may also use .NS and .NE at the beginning of a document follow- 
ing .AS 2 and .AE to place the notation list on the Memorandum for File 
cover sheet {5.6}. If you give notations at the beginning without .AS 2, 
they will be saved and printed at the end of the document. 



5.4. Table of Contents (.TC) 

For most documents, the table of contents appears at the beginning, but 
because you have to call .TC at the end of your unformatted file, this 
Technical Discussion treats it as a macro for the end of the document, mm 
produces the table of contents at the end because the entire document must 
be processed before the table of contents can be generated from gathered 
section headings. 

This macro normally appears once at the end of the document, after the 
Signature Block (S.l) and Notations {5.3) macros. 

The .TC macro generates a table of contents containing heading levels 
that were saved for the table of contents as determined by the value of the 
CI register {3.5.3}. 

.TC [slevel] [spacing] [tlevel] [tab] [hi] [h2] [h3] [h4] [/i5] 

Arguments to .TC control spacing before each entry, placement of associated 
page number, and additional text on the first page of the table of contents 
before the word "CONTENTS." 

Spacing before each entry is controlled by the first and second argu- 
ments (slevel and spacing). Headings whose levels are less than or equal to 
slevel will have spacing blank lines (halves of a vertical space) before them. 
Both slevel and spacing default to 1. This means that first-level headings are 
preceded by one blank line (one-half a vertical space). The slevel argument 
does not control what levels of heading have been saved; saving of head- 
ings is the function of the CI register. 

The third and fourth arguments {tlevel and tab) control placement of the 
associated page number for each heading. Page numbers can be justified at 
the right margin with either blanks or dots (called leaders) separating the 
heading text from the page number, or the page numbers can follow the 
heading text. 
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■ For headings whose level is less than or equal to tievel (default 
2), page numbers are justified at the right margin. Here, the 
value of tab determines the character used to separate heading 
text from page number. If tab is (default value), dots (that is, 
leaders) are used. If tab is greater than 0, spaces are used. 

■ For headings whose level is greater than tievel, page numbers 
are separated from heading text by two spaces (that is, page 
numbers are "ragged right," not right justified). 

Additional arguments {hi ... h5) are horizontally centered on the page 
and precede the table of contents. 



5.5. Changing the Table of Contents (.TX, .TY) 

If you call the .TC macro with at most four arguments, mm calls the 
user-exit macro .TX (without arguments) before the word "CONTENTS" is 
printed, or calls the user-exit macro .TY, and does not print the word "CON- 
TENTS." By defining .TX or .TY and calling .TC with at most four argu- 
ments, you can specify what needs to be done at the top of the first page of 
the table of contents. For example, 

.de TX 
• ce 2 

Special ytolication 
Message Transmission 
.sp 2 
.in +5n 

^jproved: \l''2.5i' 

.in 

.sp 

.TC 

yields the following output when you format the file that contains them: 
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special Application 
Message Transmission 

Approved: 



If you define the .TX macro as .TY, the word "CONTENTS" would be 
suppressed. Defining .TY as an empty macro suppresses "CONTENTS" with 
no replacement: 

.de 1Y 



By default, the first level headings appear in the table of contents left 
justified. Later levels align with the text of headings at the preceding level. 
You may change these indentations by defining the Ci string that takes a 
maximum of seven arguments corresponding to the heading levels. You 
must give at least as many arguments as are set by the CI register. With 
these registers, arguments must be scaled. For example, with "CI = 5": 

.6s Ci .251 .5i .75± 1i 1i \" troff 

or 

,ds Ci 2n to en 8n \" nroff 

Two other registers are available to change the format of the table of 
contents: 

■ By default, table of contents pages will have lower-case roman 
numeral page numbering. If the Oc register is set to 1, the .TC 
macro will not print any page number but will instead reset the 
P register to 1, It is your responsibility to give an appropriate 
page footer to specify the placement of the page number. Ordi- 
narily, the same .PF macro (page footer) used in the body of the 
document is adequate. 

■ Front matter pages, such as those listing figures and tables, will 
be produced separately unless Cp is set to 1, which causes these 
lists to appear on the same page as the table of contents. 
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5.6. Cover Sheet (.CS) 

Like the table of contents macro, you call the cover sheet macro (.CS) at 
the end of the document, even though you usually put a cover sheet at the 
beginning. .CS generates a cover sheet in either the released paper or 
memorandum type of the formal memorandum style. 

•CS [pages [other [total [figs [tbls [refs] ]]]]] 

All other information for the cover sheet is obtained from data given before 
the .MT macro call {4.1.1). If you use the memorandum type, the .CS macro 
generates the "Cover Sheet for Technical Memorandum". The data that 
appear in the lower left corner of the memorandum cover sheet (counts of: 
pages of text, other pages, total pages, figures, tables, and references) are 
generated automatically (0 is used for "other pages"). You may change these 
values by supplying the corresponding arguments to the .CS macro. If you 
use the released-paper style, all arguments to .CS are ignored. 



5.7. References (.RS, .RF, .RP) 

Obtain automatically numbered references by typing \*(Rf (invoking 
the string Rf ) immediately after the text you want to reference. This places 
the next sequential reference number (in a smaller point size) enclosed in 
brackets one-half line above the text you reference, mm keeps reference 
count in the Rf number register, mm uses the number register :R to print 
the reference number for each reference call in the text (\*(Rf). You may 
change the format or value of the :R register to effect the reference marks, 
without affecting the total count of references. 

Use the .RS and .RF macros to delimit text of each reference. 

Text to be referencedX^iBf 
.RS 

Reference 
.RF 
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The .RS macro takes an optional argument, a string-name. For example, 

.RS aA 

Reference 
.RF 

The string aA is assigned the current reference number. You may use 
this string later in the document as the string call, \*(aA, to reference text 
that must be labeled with a prior reference number. The reference is 
enclosed in brackets one-half line above the text to be referenced. You do 
not need a .RS/.RF pair for subsequent references. 

You may use the .RP (reference page) macro to produce reference pages 
anywhere else within a document (that is, after each major section). It is 
not needed to produce a separate reference page with default spacings at 
the end of the document. 

The .RP macro produces the reference page. 
.RP [argl [argl] ] 

Two arguments may be used with .RP. Possibilities for the first argument 
are as follows: 



Argument 1 


Function 





Reset reference counter (default). 


1 


Do not set reference counter. 



Possibilities for the second argument are as follows: 



Argument 2 


Function 





Put on separate page (default). 


1 


Do not cause a following .SK. 


2 


Do not cause a preceding .SK. 


3 


Do not cause a preceding or following .SK. 



This page contains the reference items (that is, reference text enclosed 
within .RS/.RF pairs). Reference items are separated by a space (one-half a 
vertical space) unless you set the Ls register. to to suppress this spacing. 
You may change the reference page title by defining the Rp string: 
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.6s Bp ''New Title 

If no .SK macro is issued by the .RP macro, a single blank line separates 
the references from the following /preceding text. You may wish to adjust 
spacing. For example, to produce references at the end of each major sec- 
tion: 

.sp 3 
.HP 1 2 

.H 1 "Next Sectican" 
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6.1. Bold, Italic, and Roman Fonts (.B, .1, .R) 

mm provides three macros for changing the prevailing font of a docu- 
ment 

.B [bold-arg [previous-font-arg] ] 
.1 [italic-arg [previous-font-arg] ] ... 
.R 

When you invoke it without arguments, .B changes the font to bold, 
and .1 changes to underlining (italic), mm uses these fonts until you invoke 
another font macro, such as the .R macro, which restores roman font. Thus, 

.1 

here is sane text. 
.R 

yields underlined text via the nroff and italic text via the troff formatter. 

If you invoke the .B or .1 macro with one argument, that argument 
appears in the appropriate font (underlined in the nroff formatter for .1). 
Then mm restores the previous font (underlining is turned off in the nroff 
formatter). If you give two or more arguments (maximum six) with a .B or 
.1 macro call, the second argument is concatenated to the first with no inter- 
vening space (1/12 space if the first font is italic), but it is printed in the 
previous font. Remaining pairs of arguments are similarly alternated. For 
example, 

.1 italic " words of text " right- justified 
produces 

itnlic words of text right -justified 

The .B and J macros alternate with the prevailing font at the time the 
macros are invoked. To alternate specific pairs of fonts, the following mac- 
ros are available: 

.IB .BI .IR .RI .RB .BR 
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Each macro takes a maximum of six arguments and alternates arguments 
between specified fonts. 

When you use a terminal that cannot underline, you can insert the fol- 
lowing line in the parameter setting segment to eliminate all underlining: 

.m ul 
.rm oi 

mm handles font changes in headings separately (3.5.2.4). 

6.2. Justification of Right Margin (.SA) 

Use the .SA macro to set right-margin justification for the main body of 
text. 

.SA [arg] 

Choose from two justification flags: current and default. Initially, mm sets 
both flags for no justification in the nroff formatter and for justification in 
the troff formatter. An argument to .SA causes the following action: 



Argument 


Meaning 





Sets both flags to no justification. 
It acts like the .na request. 


1 


Sets both flags to cause both 
right and left justification, 
the same as the .ad request. 


Omitted 


Causes the current flag to be copied 
from the default flag, thus 
performing either a .na or .ad 
depending on the default condition. 



Figure 13: Arguments to the .SA Macro 
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In general, you can use the no adjust request (.na) to ensure that 
justification is turned off. Use .SA to restore justification, rather than the .ad 
request. Specify justification or no justification for the remainder of the text 
by inserting .SA 1 or .SA one time at the parameter setting segment. 



6.3. Skipping Pages (.SK) 

The .SK macro skips pages but retains the usual header and footer pro- 
cessing. 

.SK [pages] 

If you omit the pages argument, or make it null or 0, .SK skips to the top of 
the next page unless it is currently at the top of a page (then it does noth- 
ing). .SK w skips n pages. .SK positions text that follows it at the top of a 
page, while .SK 1 leaves one page blank except for the header and footer. 



6.4. Forcing an Odd Page (.OP) 

Use the .OP macro to ensure that formatted output text following the 
macro begins at the top of an odd-numbered page. 

.OP 

■ If currently at the top of an odd-numbered page, text output 
begins on that page (no motion takes place). 

■ If currently on an even page, text resumes printing at the top of 
the next page, 

■ If currently on an odd page (but not at the top of the page), one 
blank page is produced, and printing resumes on the next odd- 
numbered page after that. 
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6.5. Setting Point Size and Vertical Spacing (.S) 

Change the prevailing point size and vertical spacing by invoking the .S 
macro, 

.S [point size [vertical_spacing] ] 

In the troff formatter, the default point size (obtained from the mm register 
S (8.4)) is 10 points, and the vertical spacing is 12 points (six lines per inch). 
You may use the mnemonics D (default value), C (current value), and P 
(previous value) for both arguments. 

■ If an argument is negative, current value is decremented by 
the specified amount. 

■ If an argument is positive, current value is incremented by the 
specified amount. 

■ If an argument is unsigned, it becomes the new value. 

■ If there are no arguments, the •S macro defaults to P. 

■ If you specify the first argument but not the second, then 
(default) D is used for the vertical spacing. 

Default value for vertical spacing is always two points greater than the 
current point size. Footnotes {3.3} are two points smaller than the body 
with an additional 3-point space between footnotes. A null ("") value for 
either argument defaults to C (current value). Thus, if « is a numeric value: 
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Macro and 




Argument 


Result 


•S 


.SPP 


.S n 


.SCn 


.S n 


.SnC 


S n 


.Sn D 


S 


.SCD 


S 


.sec 


.S nn 


.S n n 



Figure 14: Arguments to the .S Macro 



P means previous value, D means default value (usually 10 point), and C 
means current value 

If you make the first argument greater than 99, the default point size (10 
points) is restored. If the second argument is greater than 99, mm uses the 
default vertical spacing (current point size plus two points). For example. 



.S 100 = .S 10 12 
.S 14 111 = .S 14 16 

The .SM macro allows you to reduce by one point the size of a string. 

• SM stringi [string2] [ strings ] 

If you omit the third argument {stringS), the first argument {string!) is 
made smaller and is concatenated with the second argument (stringi), if 
specified. If all three arguments are present (even if any are null), the 
second argument is made smaller and all three arguments are concatenated. 
For example. 
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Input 




.SMX 


X 


.SM X Y 


XY 


.SM Y X Y 


YXY 


.SM YXYX 


YXYX 


.SM YXYX ) 


YXYX) 


.SM ( YXYX ) 


(YXYX) 


.SM Y XYX 


YXYX 



6.6. Producing Accents 

The following example shows that you may use strings to produce 
accents for letters: 



Name 


Input 


Output 


Grave accent 


cV 


c 


Acute accent 


e\*' 


e 


Circumflex 


oV^ 


6 


Tilde 


nV 


n 


Cedilla 


c\% 


^ 


Lower-case umlaut 


uV: 


u 


Upper-case umlaut 







6.7. Two-Column Output (.2C, .IC) 

The mm text formatting macro package can format two-columns on a 
page. The ,20 macro begins 2-column processing that continues until a .IC 
macro (1-column processing) is encountered. 



mm: TECHNICAL DISCUSSION 93 



Miscellaneous Macros 



.2C 

text and formatting requests (except another .2C) 
.1C 

In 2-column processing, each physical page is thought of as containing 2- 
coiumnar "pages" of equal (but smaller) "page" width. Page headers and 
footers are not affected by 2-column processing. The .2C macro does not 
balance 2-column output. 

It is possible to have full-page width footnotes and displays when in 2- 
column mode though footnotes and displays are by default narrow in 2- 
column mode and wide in 1-column mode. .WC controls footnote and 
display width, which is specified in arguments. .WC WD FF, for instance, 
causes all displays to be wide and all footnotes to be the same width. 
.WC N reinstates the defaults. If you give conflicting settings to .WC, mm 
selects the last one: a .WC WF -WF command has the effect of a .WC -WF. 
Arguments to ,WC are as follows: 



Argument: Meaning: 

N Default mode (-WF, -FF, -WD, FB). 

WF Wide footnotes (even in 2-column mode). 

-WF DEFAULT: Turn off WF. Footnotes follow column mode; 

wide in 1-column mode (.IC), narrow in 2-column 
mode (.2C), unless FF is set, 

FF First footnote. All footnotes have same width as first 

footnote encountered for that page. 

-FF DEFAULT: Turn off FF. Footnote style follows settings 

of WF or -WF. 

WD Wide displays (even in 2-column mode). 

-WD DEFAULT: Displays follow the column mode in effect 

when display is encountered. 

FB DEFAULT: Floating displays cause a break when output 

on the current page. 

~"FB Floating displays on current page do not cause a break. 
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6.8. Inserting Text Interactively (.RD) 

The .RD (read insertion) macro allows you to stop the standard output 
of a document and to read text from the standard input until two consecu- 
tive newline characters are found. 

.RD [prompt [diversion [string] ] ] 

When newline characters are encountered, normal output is resumed. 

■ The prompt argument prints at the terminal. If not given, 
.RD signals you with a BEL on terminal output, 

■ The diversion argument allows you to save all text typed in 
after the prompt in a macro whose name is that of the diver- 
sion. 

■ The string argument allows you to save for later reference the 
first line following the prompt in the named string. 

The .RD macro follows the formatting conventions in effect. Thus, the 
following examples assume that the .RD is invoked with line-filling off 
(•nf): 

.RD Name aA bB 
produces 

Name: J. Jones (you type name) 

16 Elm Rd. , 

Piscataway 

The diverted macro .aA will contain 

J. Jones 
16 Elm Rd. , 
Piscataway 

The string bB (\*(bB) contains "J. Jones." 

A newline character followed by an EOF (user specifiable CONTROL-d) 
also allows you to resume normal output. 
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6.9. sees Release Identification (RE) 

The RE string contains the SCCS release and the mm text formatting 
macro package current version level. For example, 

Ihis is version \»(RE of the nacres, 
produces 



This is version 10.129 of the macros. 

This information is useful in analyzing suspected bugs in mm. The 
easiest way to have the release identification number appear in the output is 
to specify -rDl {8.4} on the command line. This causes the RE string to be 
output as part of the page header {3,4.1}. 



6.10. Extending and Changing tlie Macros 

6.10.1. Naming Conventions 

In this part, the folloviring conventions are used to describe names: 
n Digit 

a Lower-case letter 
A Upper-case letter 

X Any alphanumeric character (n, a, or A, that is, letter or digit) 
s Any nonalphanumeric character (special character) 

Request, macro, and string names are kept by the formatters in a single 
internal table; therefore, there must be no duplication among such names. 
Number register names are kept in a separate table. 
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6.10.1.1. Components Used by Formatters 

Requests: aa (most common) 

an (only one, currently: c2) 

Registers: aa (normal) 
.X (normal) 

.s (only one, currently: .$) 
a, (only one, currently: c.) 

6.10.1.2. Components Used by mm 

Macros and Strings: A, AA, Aa (accessible to you; for example, macros 

.P and .HU, strings F, BU, and Lt) 

nA (accessible to you; only two, currently: IC and 
2C) 

aA (accessible to you; only one, currently: nP) 

$ (accessible to you; only the seven accents, 
currently {6.6}) 

registers: An, Aa (accessible to you; for example, HI, Fg) 

A (accessible to you; meant to be set on the com- 
mand line; for example, C) 



6.10.2. Sample Extensions 
6.10.2.1. Appendix Headings 

The following is a way of generating and numbering appendix head- 
ings: 
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♦nr Hu 1 
.nr a 
.de aH 
.nr a +1 
.nr P 

.PH ' '^^pendix: \\na-\\\\nP' 
.SK 

.HU "\\$r' 



After the above initialization and definition, each call of the form 
.aH Title" 

begins a new page (with the page header changed to "Appendix a-n") and 
generates an unnumbered heading of title, which, if desired, can be saved 
for the table of contents. To center appendix titles the He register must be 
set to 1 {3.5.2.3}. 

6.10.2.2. Hanging Indent with Tabs. 

The following example uses the hanging indent feature of variable-item 
lists (3.2.4). A user-defined macro is defined to accept four arguments that 
make up the mark. In the output, each argument is to be separated from the 
previous one by a tab; tab settings are defined later. Since the first argu- 
ment may begin with a period or apostrophe, the \& is used so that the for- 
matter does not interpret such a line as a formatter request or macro call. 
The 2-character sequence \& is understood by formatters to be a zero-width 
space. It causes no output characters to appear, but it removes the special 
meaning of a leading period or apostrophe. The \t is translated by the for- 
matter into a tab. The \c is used to concatenate the input text that follows 
the macro call to the line built by the macro. 
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.de aX 
.LI 

Ns&.\\$ 1\t\\$2\t\\$3\t\\$4\t\c 

.ta 8 14 20 24 
.VL 1.0i 

,aX .lih off \- no 
No hyiiis^'ti*^' 

Autonatic hyphenation is turned off. 
Words containing hyphens 

(for exanple, nother-in-law) nay still be split across lines, 

,aX .hy on V- no 

Hyphenate. 

Autonatic hyphenation is turned on. 
.aX .hcX c none none no 

Hyphenation indicator character is set to "c" or removed. 

During text processing, the indicator is suppressed 

and will not appear in the output. 

Prepeniing the indicator to a word has the effect 

of preventing hyphenation of that vrord. 

.LE 



The resulting output is: 

- 1 - 



No hyphenation. Automatic hyphenation is turned off. Wor 
containing hyphens (for example, mother-in-law) may sti] 
be split across lines. 

Hyphenate. Automatic hyphenation is turned on. 

Hyphenation indicator character is set to "c" or removed. 
During text processing, the indicator is suppressed and 
will not appear in the output. Prepending the indicator 
a word has the effect of preventing hyphenation of that 
word . 
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6.11. Vertical Spacing (.SP) 

There exists several ways of obtaining vertical spacing, all with different 
effects. The .sp request spaces the number of lines you specify unless you 
turn off spacing with ^ns, then mm ignores the .sp request. You can restore 
spacing with the .rs request. 

Spacing is turned off automatically at the end of a page header to elim- 
inate spacing by a .sp or .bp request that happens to occur at the top of a 
page. 

Use the .SP macro to avoid the accumulation of vertical space by succes- 
sive macro calls. 

.SP [lines] 

Several .SP calls in a row will not produce the sum of the arguments but 
only the maximum argument. For example, the following produces only 
three blank lines: 

• SP 2 
.SP 3 
.SP 



Many mm macros use .SP for spacing. For example, if you immediately 
follow .LE 1 (3.2.1) with .P {3.1}, mm produces only a single blank line 
(one-half vertical space) between the end of the list and the following para- 
graph. An omitted argument to .SP defaults to one blank line (one vertical 
space). Negative arguments are not permitted. The argument must be uns- 
ealed, but fractional amounts are permitted. The .ns request also inhibits 
the .SP macro (as well as the .sp request). 
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7.1. Error Terminations 

When an mm macro detects an error, it performs the following actions: 

■ It performs a line break. 

■ It prints the formatter output buffer (which may contain some 
text) to avoid confusion regarding location of the error. 

■ It prints a short message giving the name of the macro that 
detected the error, type of error, and approximate line 
number in the current input file of the last processed input 
line. The last section of this chapter explains error messages. 

■ It stops processing unless register D (8.4) has a positive value. 
In the latter case, it continues processing even though the 
output is guaranteed to be garbled from that point on. 

The error message outputs directly to your terminal. If you are using an 
output filter, such as 300, 450, or hp to postprocess the nroff formatter out- 
put, this message may be garbled by being intermixed with text that is held 
in that filter's output buffer. If you are using any eqn/neqn or Ibl material, 
and if the -olist option of the formatter causes the last page of the docu- 
ment not to be printed, a harmless "broken pipe" message may result. 



7.2. Disappearance of Output 

Disappearance of output usually occurs because of an unclosed diversion 
(for example, a missing .DE or .FE macro). Fortunately, macros that use 
diversions are careful about it, and these macros check to make sure that 
illegal nestings do not occur. If any error message is issued about a missing 
.DE or .FE, search backwards from the termination point and look for the 
corresponding .DF, .DS, or .FS (since you must use these macros in pairs). 
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The command grep -n "^\4EDFRTl[EFNQSr files . , . prints all the •DF, 
.DS, .DE, .EQ, .EN, .FS, .FE, .RS, .RF, .TS, and TE macros found in files 
each preceded by its file name and the line number in that file. Use this 
listing to check for illegal nesting and /or omission of these macros. Also, 
the checkmm programs finds mismatched macro pairs. 



7.3. Error Messages 

An mm error message has a standard part followed by a variable part. 
The standard part has the form: 

ERRCR : (file)input line n: 

Variable parts consist of a descriptive message usually beginning with a 
macro name. Appendix D lists them in alphabetical order by macro name, 
each with a more complete explanation. 
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8. Using the mm Command Line 



Use the mm command line to print documents using nroff and the mm 
macros. Use mmt to format documents with troff and the macros. 

8.1. Typical mm Command Lines and Options 

These are the typical command lines for mm {options are described 
below). Pipe results to a printer or phototypesetter as appropriate, or 
redirect output to a file. 

■ Text without tables or equations: 

mm [options] file . . . 
mmt options file , . . 

■ Text with tables: 

mm -t options file . . . 
mmt -t options file . , . 

■ Text with equations: 

mm -e options file . . . 
mmt -e options file . . . 

■ Text with line pictures: 

mmt -p options file . . . 

■ Text with graphs: 

mmt -g options file . . . 
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■ Text with both tables and equations: 

mm — t — e options file . . . 
mmt — t — e options file . . . 

■ Text with tables, equations, pictures and graphs: 

mmt — t — e — p — g options file ... 

You can put options in any order you wish, but you must put them before 
the file name(s). 

-e calls neqn (mm) or eqn (mmt) and causes it to read 
/usr/pub/eqnchar 

-c calls col(l) 

-t calls tbl 

-p calls pic (use this with mmt only) 
-g calls grap (use this with mmt only) 
-E calls the -e option of nroff 

-12 specifies that 12 characters per inch, or 78 characters per normal out- 
put line (6 1/2 inches) are output. This specification is called "12- 
pitch mode." The pitch switch on your printer should be set to 12. 
By default, 10 characters per inch are output. 

"Tttyjype 

specifies to which output device you are sending your output. 

When you format a document, prepare the output for a particular type of 
terminal, because the output may require features that are specific to that 
terminal. For example, some terminals produce reverse paper motion or 
half-line paper motion in both directions. A list of the supported terminals 
you may use with mm appears in the following section. (Check with your 
system administrator for a list of locally supported devices.) 
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If you use two-column processing {6.7}, you must specify either the -c 
option to mm [mm uses col(l) automatically for many terminal types] or 
you must postprocess nroff formatter output with col(l). In the latter case, 
you must specify the -T37 terminal type to the nroff formatter, take care 
not to specify the -h option, and process the output of col(l) by the 
appropriate terminal filter (for example, 450); mm with the -c option han- 
dles all this automatically. 



8.2. Command Line Options for Specifying a Printer 

Use one of the following arguments to the mm command line option 
-T to specify an output device to the formatter. To specify a program that 
drives the printer, use the -T option. It is a way of telling the formatter to 
carry out certain operations that your particular printer program can exe- 
cute. Ask your system administrator what argument to -T is appropriate 
for your text formatting set-up. A list of all supported arguments (values for 
ttyjype) and the devices they signify are as follows: 

-Tttyjype 

2631 
2631-c 

2631-e 
300 
300-12 

300s 
300S-12 

37 
382 
4000a 
450 
450-12 

832 
8510 

IP 
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Hewlett-Packard 2631 printer in regular mode 
Hewlett-Packard 2631 printer in compressed 
mode 

Hewlett-Packard 2631 printer in expanded mode 
DASI-300 printer 

DASI-300 terminal set to 12-pitch (12 characters 
per inch) 

DASI-300S printer (300S is a synonym) 
DASI-300S printer set to 12-pitch (12 characters 
per inch) (300S-12 is a synonym) 
Teletype Model 37 terminal 
DTC-382 

Trendata 4000a terminal (4000A is a synonym) 
DASI-450 (Diablo Hyterm) printer 
DASI-450 terminal set to 12-pitch (12 characters 
per inch) 

Anderson Jacobson 832 terminal 
C.ITOH printer 

generic name for printers that can underline 
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and tab. (All text using reverse linefeeds, such 
as those having tables, that is sent to Ip must be 
processed with col.) Ip is the default device for 
mm. 

tnSOO GE Terminet 300 terminal 

X printers equipped with TX print train 



8.3. Giving nroff or troff the -mm Fiag 

You may also use the mm package by including the -mm flag as an 
argument to nroff or troff. The -mm flag causes the file 
/usr/lib/tmac/tmac.m to be read and processed before any other files. This 
action: 

■ defines the Memorandum Macros 

■ sets default values for various parameters 

■ initializes the formatter to be ready to process input text files 



8.4. Setting Number Registers from the Command 
Line 

With mm, you commonly use number registers to hold parameter values 
that control various aspects of output style. You can change many of these 
values within the text files with .nr requests. In addition, you can set some 
of these registers from the command line. This is useful when parameters 
should not be embedded within the input text. The number register mean- 
ings are 

w = 1 has effect of invoking the .AF macro without an 
argument {4.1.7). 

Sets type of copy (for example, DRAFT) to be printed at 
bottom of each page (3.4.3). 
n = 1 for OFFICIAL FILE COPY, 
n « 2 for DATE FILE COPY. 

w = 3 for DRAFT with single spacing and default para- 
graph style. 



— rA^2 
-rCn 
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M = 4 for DRAFT with double spacing and 10-space 
paragraph indent. 

-rDl Sets debug mode. 

This flag requests formatter to continue processing even 
if mm detects errors that would otherwise cause termi- 
nation. It also includes some debugging information in 
the default page header (3.4.1). 

_rE« Controls font of Subject /Date /From fields. 

n = 0, fields are bold (default for the troff formatter). 
« = 1, fields are roman font (regular text-default for the 
nroff formatter). 

-rU Sets length of physical page to k lines. 

For the nroff formatter, k is an unsealed number 
representing lines. 

For the troff formatter, k must be scaled. 
Default value is 66 lines per page. 

This flag is used, for example, when directing output to 
a Versatec printer. 

-rN/t Specifles page numbering style (See Figure 8-1). 

w = (default), all pages get the prevailing header 
{3.4.1}. 

„ = 1, page header replaces footer on page 1 only. 
M = 2, page header is omitted from page 1. 
« = 3, "section-page" numbering (3.5.3) occurs (.FD 
(3.3.1) and .RP (5.7) defines footnote and reference 
numbering in sections). 

n = 4, default page header is suppressed; however, a 

user-specified header is not affected. 

N = 5, "section-page" and "section-figure" numbering 

occurs. 
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n 


Page 1 


Pages 2-end 





header 


header 


1 


header replaces footer 


header 


2 


no header 


header 


3 


"section-page" as footer 


same as page 1 


4 


no header 


no header unless .PH defined 


5 


"section-page" as footer 


same as page 1 




and "section-figure" 



Figure 15: Effects of the n Register on Page Numbering Style 



Contents of the prevailing header and footer do not depend 
on number register N value; N controls whether the header 
(N=3) or the footer (N=5) is printed, as well as the page 
numbering style. If header and footer are null {3.4}, the 
value of N is irrelevant. 

-rOk Offsets output k spaces to the right. 

For the nroff formatter, k is an unsealed number represent- 
ing lines or character positions. 
For the troff formatter, k must be scaled. 
This flag is helpful for adjusting output positioning on some 
terminals. The default offset if this register is not set on the 
command line is 0.75 inch (nroff) and 0.5 inch (troff). 

-rPw Specifies that pages of the document are to be numbered 

starting with «. 

This register may also be set via a .nr request in the input 
text. 

-rS« Sets point size and vertical spacing for the document. 

The default n is 10, that is, 10-point type on 12-point vertical 
spacing, giving six lines per inch {6.5} . 
This flag applies to the troff formatter only. 

-rT« Provides register settings for certain devices. 

If n is 1, line length and page offset are set to 80 and 3, 
respectively. 

Setting « to 2 changes the page length to 84 lines per page 
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and inhibits underlining; it is meant for output sent to the 
Versatec printer. 

This flag applies to the nroff formatter only. 

— rUl Controls underlining of section headings. This flag causes 

only letters and digits to be underlined. Otherwise, all char- 
acters (including spaces) are underlined {3.5.2.4.2}. This flag 
applies to the nroff formatter only. 

-rWfc Sets page width (line length and title length) to it. 

For the nroff formatter, k is an unsealed number represent- 
ing character positions. 
For the troff formatter, k must be scaled. 
This flag can be used to change page width from the default 
value of 6 inches (60 characters in 10 pitch or 72 characters 
in 12 pitch). 
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9.1. Appendix A: mm Macro Name Summary 

The following listing shows all the mm macros and their usage. Each 
item in the list gives a definition of the macro followed by its normal for- 
mat and arguments. The numbers enclosed in braces {) show the section in 
this technical discussion where a complete explanation of each macro may 
be found. You do not call macros marked with an asterisk directly. They 
are "user exits** that you define, and they are called by the mm macros from 
inside header, footer, or other macros. 

.IC 1 -column processing {6.7) 
.IC 

•2C 2-column processing (6.7) 
.IC 

.AE Abstract end {4.2,1} 
.AE 

•AF Alternate format of "subject:/date:/from:" block (4.1.7) 
.AF [''name of firm''] 

.AL Automatically incremented list start (3.2.2) 
.AL [type [text-indent [1] ] ] 

.AS Abstract start (4.2.1) 
.AS [arg [indent] ] 

.AT Author's title (4.1.6) 
.PlI [title] ... 

.AU Author information (4.1.5) 

.AU name [initials [loc [dept [ext [room [arg [arg [arg] ]]]]]]] 

.AV Approval signature (5.2) 
.AV [name [1] ] 

.B bold (6.1) 

.B [bold-arg [previous-font-arg] ] . . . 
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.BE Bottom block end (4.2.3) 
.BE 

.BI bold/italic {6.1} 

.BI [bold-arg [italic-arg [bold [italic [bold [italic] ]]]]] 

.BL Bullet list start {3.2.5} 
.BL [text-indent [1] ] 

.BR bold/roman {6.1} 

.BR [bold-arg [roman-arg [bold [roman [bold [roman] ] 1 ] ] ] 

.BS Bottom block start {4.2.3) 
.BS 

.CS Cover sheet {5.6} 

.CS [pages [other [total [figs [tbls [refs] ]]]]] 

.DE Display end {3.6.1) 
.DE 

.DP Display floating start {3.6.2} 
.DF [format [fill [rindent] ] ] 

.DL Dash list start {3.2.5} 
.DL [text-indent [1] ] 

•OS Display static start {3.6.1} 
.OS [format [fill [rindent] ] ] 

.EC Equation caption {3.9} 

.EC [title [override [flag] ] ] 

.EF Even-page footer {3,4.4} 
.EF [arg] 

.EH Even-page header {3.4.2} 
.EH [arg] 

.EN End equation display {3.8} 
.EN 

.EQ Equation display start {3.8} 
.EQ [label] 

.EX Exhibit caption {3.9} 

.EX [title [override [flag] ] ] 
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.FC Formal closing {5.1} 
.FC [closing] 

.FD Footnote default format {3.3.1} 
.FD [arg [1] ] 

.FE Footnote end {3.3} 
.FE 

.FG Figure title {3.9} 

.FG [title [override [flag] ] ] 

.FS Footnote start {3.3} 
.FS [label] 

.H Heading— numbered {3.5} 

.H level [heading-text [heading-suffix] ] 

.HC Hyphenation character {1.4.4} 
.HC [hyphenation-indicator] 

.HM Heading mark style (Arabic or roman numerals, or letters) 
{3.5.2.6} 

.HM [argl]„,[arg7] 

.HU Heading— unnumbered {3.5.1} 
.HU headingrtext 

.HX* Heading user exit X (before printing heading) {3.5.4} 
.HX dlevel rlevel heading-text 

.HY* Heading user exit Y (before printing heading) {3.5.4} 
.HY dlevel rlevel heading-text 

.HZ* Heading user exit Z (after printing heading) {3.5.4} 
.HZ dlevel rlevel heading-text 

.1 italic (underline in the nroff formatter) {6.1} 

.1 [italic-arg [previous-font-arg] ] ... 

.lA Inside address start {4.5.3} 
.lA [addressee-name [title] ] 

.IB italic/bold {6.1} 

.IB [italic-arg [bold-arg [italic [bold [italic [bold] ]]]]] 
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IE 



Inside address end {4.5.3) 



IR 



.IE 

italic/roman {6,1} 



.IR [italic-arg [roman-arg [italic [roman [italic [roman] ] ] ] ] ] 

LB List begin {3.2,7} 

.LB text-indent mark-indent pad type [mark [Ll-space] ] 



LC List-status clear {3.2.8} 
.LC [list-level] 

LT Letter Type {4.5.1) 
.LT [arg] 

LE List end {3.2,1} 
.LE [1] 

LI List item {3.2.1) 

.LI [mark [1] ] 

LO Letter Options {4.5.4) 
.LO type [arg] 

ML Marked list start {3.2.3} 
.ML mark [text-indent [I] ] 

MT Memorandum type {4.1.1} 

.MT [type [addressee] ] or MT [4] [1] 

ND New date {4.1.3} 
•ND new-date 

NE Notation end {5.3} 
.NE 

NS Notation start {5.3} 

.NS [arg [1] ] nP" Double-line indented paragraphs {3.1.2} 
.nP 

OF Odd-page footer {3.4.4} 
•OF [arg] 

OH Odd-page header {3.4,2} 
.OH [arg] 



[LB-space] 
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.OK Other keywords for the Technical Memorandum cover sheet 
{4.2.2} 

.OK [keyword] , . . 

.OP Odd page {6.4} 
.OP 

.P Paragraph {3.1} 

.P [type] 

.PF Page footer {3.4.3} 
.PF [arg] 

.PH Page header {3.4.1} 
.PH [arg] 

,PM Proprietary marking {4.3} 
.PM [code] 

.PX* Page-header user exit {3.4.9} 
.PX 

.R Return to regular (roman) font {6,1} 

.R 

.RB roman/bold {6.1} 

.RB [roman-arg [bold-arg [roman [italic [roman [italic] ] ] ] ] 1 

,RD Read insertion from terminal {6.8} 
.RD [prompt [diversion [string] ] ] 

.RF Reference end {5.7} 
.RF 

.RI roman/italic {6.1} 

.RI [roman-arg [italic-arg [roman [italic [roman [italic] ] ] ] ] ] 

.RL Reference list start {3,2.5} 
.RL [text-indent [1] ] 

.RP Produce reference page {5.7} 
.RP [arg [arg] 

.RS Reference start {5,7} 
.RS [string-name] 
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.S Set troff formatter point size and vertical spacing {6.5) 

.S [size [spacing] ] 

.SA Set adjustment (right-margin justification) default {6.2} 
•SA [arg] 

SG Signature line {5.1} 
•SG [arg [1] ] 

.SK Skip pages {6.3} 
.SK [pages] 

.SM Make a string smaller {6.5} 
•SM stringl [string! [stringS] ] 

.SP Space vertically {6.11} 
.SP [lines] 

.TB Table title {3.9} 

.TB [title [override [flag] ] ] 

.TC Table of contents {5.4} 

.TC [slevel [spacing [tlevel [tab [hi [hi [h3 [h4 [h5] ]]]]]]]] 

.TE Table end {3.7} 
.TE 

.TH Table header {3.7} 
TH [N] 

.TL Title of memorandum {4.1.4} 
.TL [charging'Case [filing-case] ] 

.TM Technical Memorandum number(s) {4.1.2} 
.TM [number] . . . 

.TP* Top-of-page macro {3.4.9} 
•TP 

.TS Table start {3.7} 
.TS [H] 

.TX* Table of contents user exit {5.5} 
.TX 

.TY* Table of contents user exit (suppresses "CONTENTS") {5.4.1} 
.TY 



mm: TECHNICAL DISCUSSION 1 1 5 



Appendices 

.VL Variable-item list start (3.2.4) 

.VL text-indent [mark-indent [1] ] 

•VM Vertical margins {3.4.7} 
.VM [top [bottom] ] 

.WA Writer's address start {4.5.2} 
.WA writer-name [title] 

.WC Footnote and display width control (6.7) 
.WC [format] 

.WE Writer's address end (4.5.2) 
.WE 



9.2. Appendix B: mm String Name Summary 

The following list shows the predefined string names used by the mm 
macro package. The numbers in braces {) show the section in this technical 
discussion where more information about the string can be found. 

BU Bullet (1.4.6) 
nroff : e 
troff:* 

Ci Table of contents indent list (5.4.1) 

Up to seven scaled arguments for heading levels 

DT Date (l.2) 

Current date, unless overridden 

Month, day, year (for example. May 31, 1979) 

EM Em dash string (1.4.7) 

Produces an em dash in the troff formatter and a double 
hyphen in nroff F Footnote number generator (3.3) 
nroff: \u\\n+(:p\d 
troff: \v'-.4m'\s-3\\n+(:p\s0\v'.4m' 

HP Heading font list (3.5.2.4.1) 

Up to seven codes for heading levels 1 through 7 
2 2 2 2 2 2 2 (all levels given emphasis) 
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HP Heading point size list (3.5.2.5} 

Up to seven codes for heading levels 1 through 7 

Le Title for LIST OF EQUATIONS {3.9) 

Lf Title for LIST OF FIGURES {3.9} 

Lt Title for LIST OF TABLES {3.9} 

Lx Title for LIST OF EXHIBITS {3.9} 

RE sees Release and Level of mm {6.9} 
Release.Level (for example, 15,129) 

Rf Reference number generator {5.8} 

Rp Title for References {5.8} 

Tm Trademark string {1.4.8} 

Places the letters **TM" one-half line above the text that it fol- 
lows Seven accent strings are also available. (See section 6.6.) 



9.3. Appendix C: mm Number Register Summary 

The list that follows contains a description of all the predefined number 
registers used by mm. Numbers enclosed in braces {} show the section in 
this technical discussion where more information about the register can be 
found. After each description is the normal value of the register followed 
by the range of allowable values, enclosed in brackets []. The lower and 
upper limit of values are separated by a colon (:). An asterisk attached to a 
register name means that this register can be set only from the command 
line or before the mm macro definitions are read by the formatter. Sec- 
tion 1.2 has notes on setting and referencing registers. Any register having 
a single-character name can be set from the command line {8.4}. These are 
marked with a dagger (f) in the following list. 

A * t Handles preprinted forms and logo 
{8.4} 0, [0:2] 

Au Inhibits printing of author information 
{4.1.5} h [0:11 
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C * t Copy type (original, DRAFT, and so on) 
{8.4} (Original), [0:4] 

CI Level of headings saved for table of contents 

{3.5.3} 2, [0:7] 

Cp Placement of list of figures, and so on 
{3.9} 1 (on separate pages), [0:1] 

D *t Debug flag 
{8.4} 0, [0:1] 

De Display eject register for floating dislays 
{3.6.2} 0, [0:1] 

Of Display format register for floating displays 
{3.6.2} 5, [0:5] 

Ds Static display pre- and post-space 
{3.6.1} 1, [0:1] 

E *t Controls font of the subject:/date:/from: fields 
{8.4} 1 (nroff)0(tro£f),[0:l] 

Ec Equation counter, used by .EC macro 

{3.9} 0, [0:?] 

Incremented by one for each .EC call. 

Ej Page-ejection flag for headings 

{3.5.2.1} (no eject), [0:7] 

Eq Equation label placement 

{3.8} (right-adjusted), [0:1] 

Ex Exhibit counter, used by .EX macro 
{3.9} 0, [0:?] . 

Incremented by one for each .EX call. 

Fg Figure counter, used by .FG macro 

{3.9} 0, [0:?] 

Incremented by one for each .FG call. 

Fs Footnote space (that is, spacing between footnotes) 

{3.3.2} 1, [0:?] 
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H1-H7 Heading counters for levels 1 through 7 
{3.5.2.6} 0, [0:?] 

Incremented by the .H macro of corresponding, level or the 
.HU macro if at level given by the Hu register. The H2 
through H7 registers are reset to by any .H (.HU) macro at a 
lower-numbered level. 

Hb Heading break level (after .H and .HU) 
(3.5.2.2) 1, [0:7] 

He Heading centering level for .H and .HU 
{3.5.2.3) (no centered headings), [0:7] 

Hi Heading temporary indent (after .H and .HU) 
{3.5.2.2) 1 (indent as paragraph), [0:2] 

Hs Heading space level (after -H and .HU) 

(3.5.2.2) 2 (space only after .H 1 and .H 2), [0:7] 

Ht Heading type (for .H: single or concatenated numbers) 
(3.5.2.6) (concatenated numbers: 1.1.1, and so on), [0:1] 

Hu Heading level for unnumbered heading (.HU) 
(3.5.1) 2 (.HU at the same level as .H 2), [0:7] 

Hy Hyphenation control for body of document 
(1.4.4) (automatic hyphenation off), [0:1] 

L * t Length of page 
(8.4) 66, [20:?] 

(Hi, [2i:?] in troff formatter) 

Le List of equations 

(3.9) (list not produced) [0:1] 

Lf List of figures 

{3.9} 1 (list produced) [0:1] 

Li List indent 

(3.2.1) 6 (nroff) 5 (troff), [0:?] 

Ls List spacing between items by level 

(3.2.1) 6 (spacing between all levels) [0:6] 

Lt List of tables 

(3.9) 1 (list produced) [0:1] 
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Lx List of exhibits 

(3.9) 1 (list produced) [0:1] 

N * t Numbering style 
{8.4} a [0:5] 

Np Numbering style for paragraphs 
{3.1.2} (unnumbered) [0:1] 

O *t Offset of page 
{8.4} 75u [0:?] 

(0.5i, [Oi:?] in troff formatter) 

For nroff formatter, these values are unsealed numbers 
representing lines or character positions. For troff formatter, 
these values must be scaled. 

Oc Table of contents page numbering style 
(5.4.1} (lower-case roman), [0:1] 

Of Figure caption style 

{3.9} (period separator), [0:1] Pf Page number managed by 
mm 

{8.4} 0, [0:?] 

Pi Paragraph indent 

{3.1.3} 5 (nroff) 3 (troff), [0:?] 

Ps Paragraph spacing 

{3.1.1} 1 (one blank space between paragraphs), [0:?] 

Pt Paragraph type 

{3.1.1} (paragraphs always left justified), [0:2] 

Pv "PRIVATE" header 

{3.4.9} (not printed), [0:2] 

Rf Reference counter, used by .RS macro 

{5.8) 0, [0:?] 

Incremented by one for each .RS call. 

S * t The troff formatter default point size 
{8.4} 10, [6:36] 

Si Standard indent for displays 

{3.6.1} 5 (nroff) 3 (troff), [0:?] 
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T » 



t 



Type of nroff output device 
(8.4) 0, [0:2] 



Tb 



Table counter, used by .TB macro 
(3.9) 0, [0:?] 

Incremented by one for each .TB call. 



U * t Underlining style (nroff ) for .H and .HU 

{8.4} (continuous underline when possible), [0:1] 

W * t Width of page (line and title length) 
{8.4} 6i, [10:1365] 

(6i, [2i:7.54i] in the troff formatter) 



When processing text using the mm macro package, mm will 
report any errors it can detect. Since the macros are written in the 
basic formatter primitives, other errors may be found and reported 
by the formatter. 

An mm error message has a standard part followed by a variable 
part. The standard part has the form: 

ERROR:(filename) input line n: 

The variable part consists of a descriptive message, usually begin- 
ning with a macro name. The variable parts are listed alphabetically 
by macro name below: 

CS:cover sheet too long 

Text of the cover sheet is too long to fit on one page. The abstract 
should be reduced or the indent of the abstract should be decreased, 

DE:no DS or DF active 

A .DE macro has been encountered, but there has not been a previ- 
ous .DS or .DF macro to match it. 

DF:illegal inside TL or AS 

Displays are not allowed in the title or abstract. 
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DF:mi$sing DE 

A .DF macro occurs within a display, that is, a .DE macro has been 
omitted or mistyped. 

DF:missing FE 

A display starts inside a footnote. The likely cause is the omission 
(or misspelling) of a .FE macro to end a previous footnote. 

DF:too many displays 

More than 26 floating displays are active at once, that is, have been 
accumulated but not yet output. 

DS:illegal inside TL or AS 

Displays are not allowed in the title or abstract. 

DSimissing DE 

A .DS macro occurs within a display, that is, a .DE has been omitted 
or mistyped. 

DS:missing FE 

A display starts inside a footnote. The likely cause is the omission 
(or misspelling) of a .FE to end a previous footnote. 

FE:no FS active 

A .FE macro has been encountered with no previous .FS to match it. 
FS:missing DE 

A footnote starts inside a display, that is, a .DS or .DF occurs 
without a matching .DE. 

FS:missing FE 

A previous .FS macro was not matched by a closing .FE, that is, an 
attempt is being made to begin a footnote inside another one. 
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H:bad argivalue 

The first argument to the .H macro must be a single digit from one 
to seven, but value has been supplied instead. 

H:missing arg 

The .H macro needs at least one argument. 

Himissing DE 

A heading macro (.H or .HU) occurs inside a display. 

Hzmissing FE 

A heading macro (.H or .HU) occurs inside a footnote. 

HU:missing arg 

The .HU macro needs one argument. 

LB:missing arg(s) 

The .LB macro requires at least four arguments, 

LB:too many nested lists 

Another list was started when there were already six active lists. 

LE:mismatched 

The .LE macro has occurred without a previous .LB or other list- ini- 
tialization macro (3.2). This is not a fatal error. The message is 
issued because there exists some problem in the preceding text. 

LI:no lists active 

The .LI macro occurred without a preceding list-initialization macro. 
The latter probably has been omitted or entered incorrectly. 

LO: Required argument missing 

The .LO macro requires an argument. 
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LO: LO argument not recognized 

You have provided an argument to .LO that it does not recognize. 

LT: LT argument not recognized 

You have provided an argument to XT that it does not recognize. 

ML:missing arg 

The .ML macro requires at least one argument. 

ND:missing arg 

The .ND macro requires one argument. 

RF:no RS active 

The .RF macro has been encountered with no previous .RS to match 
it. 

RP:mis$ing RF 

A previous .RS macro was not matched by a closing .RF. 

RSrmissing RF 

A previous .RS macro was not matched by a closing .RF. 

S:bad arg:value 

The incorrect argument value has been given for the .S macro {6.5). 

SA:bad arg:value 

The argument to the .SA macro (if any) must be either or 1. The 
incorrect argument is shown as value, 

SGrmissing DE 

The .SG macro occurred inside a display. 

SG:missing FE 

The .SG macro occurred inside a footnote. 
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SG:no authors 

The .SG macro occurred without any previous .AU macro(s). 

Check TL, AU, AS, AE, MT sequence 

The correct order of macros at the start of a memorandum is shown 
in section 4.1.8. Something has disturbed this order. 

Check TL, AU, AS, AE, NS, NE, MT sequence 

The correct order of macros at the start of a memorandum is shown 
in section 4,1.8. Something has disturbed this order. (Occurs if the 
•AS 2 (4.1.9) macro was used.) 

VL:inissing arg 

The .VL macro requires at least one argument. 

Check WA, WE, lA, IE, LT sequence 

The correct order of these macros is shown in section 4,2,6. Some- 
thing has disturbed this order. 

)W: WA macro missing 

If you use .LT, you must specify at least one .WA-.WE pair. 

)W: WA or WE macro missing 

If you use .WA or .WE, you must specify the other member of the 
macro pair. 

)W: WA, WE, or IE macro missing 

You have omitted either or both of the .lA and .IE macros. 

WC:unknown option 

An incorrect argument has been given to the .WC macro. 
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9.5. Appendix E: The Define File— 

/usr/lib/macros/strings.mm 



A" Cppyric^t (c) 1984 PH&T 

A" All Fights Reserved 

A" THIS IS UNPUBLISHED PROFKIErARy SOURCE CODK OF ATSlT 

A" Tbe cxDRyricpit notice above does not evidence any actual 

A" or intended publication of such source code, 

A" @(#)nacros: strings. nin 1.5 

A" .\"tab begins oannents. 

A" No ocnitients should appear cn the same line as the string 

.\" definiticn. 

.V 

.\" 1516 follcwing string is used by the macro m. 

A" ]S defined as logo character 

.ds ]S 

A" }Z Ccinpaiiy Name 

.ds }Z AIST Bell Laboratories 
•\" 

.\" The follcwing strings are used by the macro FM 
.\" 

A" Proprietary marking "PMV (BP, N, P and BPN) lines 1-4 



•ds ]M AI&T BEUi LABGRATCRIES - HtQFRIECAR^ 
•ds ]0 Use pursuant to G.E.I. 2.2 
.ds ]Q 
.ds ]R 

A" Proprietary marking "EM2" (CA) lines 1-4 

.ds ]A THIS DOOMENT COtmmS FRQFRIKrARY INFORMATION OF 

.ds ]F AT&T m> IS NOT TO BE DISCLOSBD OR USED EXCEPT IN 

.ds ]6 AOOQRDANCE WITH APPLICABLE CONIRACTS OR ACREE24EMTS. 

.ds ]H 

A" Proprietary marking "PM3" (CP) lines 1-4 

.ds ]I SEE FROFKEETEARir NOTICE ON OCIVER PASE 
.ds ]J 
.ds ]K 
.ds ]L 

.\" Proprietary marking "PM4" (BPP and BR) lines 1-4 

.ds ]U AIST BECIf LABGRATGRIES - WajPRLErARH (RESTRICTED) 
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.ds ]V Solely for auttorized persons having a need to tocw 
•ds ]W pursuant to G.E.I. 2.2 
.ds ]X 

.\" Proprietary marking "PM5" (ILL) lines 1-4 

,ds ]i THIS DOOOMEOT CXKTAINS PROPRIErARy INEOTMATICW OF 

.ds ] j AO&T WPT.T. LABCBAaXXOES AND IS NOT TO BE DISCLOSED, 

.ds ]k HEFPODUCED, OR HJELISHED WUHXTT mCTlW COtGWT. 

.ds ]1 THIS DOCUHEUr MUST BE IW£^(n> rx.i.vrrmxt WHEN BEING DISCARDED. 

,\" Prpptrietary marking "PM6" (CI-II) liJies 1-4 

.ds ]m CI-II 

•ds ]o Not for disclosure to ATSiT Informations Systems. 

.ds ]p Subject to FOC separation requirements under Coccputer Inquiry II 

.ds ]q 
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9.6. Appendix F: Sample Footnotes 

Input: 

.FD 10 
.P 

This exairple illustrates several footnote styles 

for both labeled and autcroatically numbered footnotes. 

First input, then output is shown. 

With the footnote style set to the 

default style, 

the first footnote is porocessedX^F 
.FS 

This is the first footnote text exan?)le. 
This is the default style (.ED 10). 
The ric^it margin is not justified, 
hyphenation is not permitted, 

text is indented, and the autonatically generated label is 

right justified in the text-indent space. 

.FE 

and followed by a second footnote. 
.FS ««««« 

This is the second footnote text exaitple. 
This is also the default style ( .ED 10) 

tut with a long footnote label provided by the user. 

• ETE 
.ED 1 

Footnote style is changed by losing the .ED macro to 
specify hyphenation, right margin justification, 
indentation, and left justification of the label. 
This produces the third footnote, \»F 
.FS 

This is the third footnote example (.ED 1), 

Ohe right margin is justified, the footnote text is indented, 

and the label is left justified in the text-indent space. 

Although not necessarily illiastrated by this exairple, 

hyphenation is permitted, 

.fe; 

and then the fourth footnote.'^ 
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.FS 

This is the fourth footnote exairple ( .FT) 1) . 
The style is the saitie as the third footnote. 

.FT) 6 

FVDOtnote style is set again via the .FT) itacro for no hyphenation, 

no ri^t margin justification, 

no indentation, and with the label left justified. 

This produces the fifth footnote. \»F 

.FS 

This is the fifth footnote exanple ( .FT) 6) . 

The right margin is not j\astified, hyphenation is not permitted, 
footnote text is not indented, 

and the label is placed at the beginning of the first line. 
•F^ 



mm: TECHNICAL DISCUSSION 129 



Appendices 

Output: 

- 1 - 

This example illustrates several footnote styles for both 
labeled and automatically numbered footnotes. First input, 
then output is shown. With the footnote style set to the 
default style, the first footnote is processedl and followed 
by a second footnote . *♦»♦♦ Footnote style is changed by 
using the . FD macro to specify hyphenation, right margin 
justification, indentation, and left justification of the 
label. This produces the third footnote, 2 and then the 
fourth footnote. r Footnote style is set again via the . FD 
macro for no hyphenation, no right margin justification, no 
indentation, and with the label left justified. This 
produces the fifth footnote. 3 



1. This is the first footnote text example. This is the 
default style ( . FD 10). The right margin is not 
justified, hyphenation is not permitted, text is 
indented, and the automatically generated label is right 
justified in the text-indent space. 
«*«** This is the second footnote text example. This is 
also the default style ( . FD 10) but with a long footnote 
label (#♦**») provided by the user. 

2. This is the third footnote example ( . PD 1). The right 
margin is justified, the footnote text is indented, and 
the label is left justified in the text-indent space. 
Although not necessarily illustrated by this example, 
hyphenation is permitted. 

r This is the fourth footnote example ( . FD 1). The style 
is the same as the third footnote. 

3. This is the fifth footnote example { . FD 6). The right 
margin is not justified, hyphenation is not permitted, 
footnote text is not indented, and the label is placed at 
the beginning of the first line. 
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9.7. Appendix G: Formal Memorandum 

Input: 

.ND "September 28, 1984" 
.TL 

Docajroent Production CoordLnator 

.AU "John Smith" JJS XF 5414 6398 7-123 madhine^Sl jjs 
.AF "Business Ccnpiter Systems, Inc." 
.MT 
.P 

Business Cotputer Systeras, Inc. (BCS) has job 

openings for people that 

can do the following tasks: 

.AL 

.LI 

Develop nethods for producing 

documentation 

,LI 

Perform duties resulting from the development of these methods. 

For exanple, 

.BL 

.u: 

Use text processiiKr with UNIX* DOCUMENTER'S VO<KBENCH» 
.FS ♦ 

Trademark of AIIST 
.FE 

(inn, nroff , tbl) to: 

.DL 

.LI 

Prepare documents and tables 
.LI 

Develop new macro conrnands 

.LE 

.LI 

Serve as a point of contact for BCS with printers and 

distributors. 

.LE 

.LI 
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If the job holder's interests and writing skills natch the 

needs of the Technical Writing Staff, 

write documents. 

.LE 

• SG 

.NS 

BCS Technical Writing Staff 
.NE 
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Appondlces 

AT&T Business Computer Systems, Inc. 



subject: Document Production 
Coordinator 



date: September 28, 1984 

from: John Smith 
XF 5414 
7-123 X6398 
machine^S 1 j js 



Business Computer Systems, Inc. (BCS) has job openings for 
people that can do the following tasks: 

1 . Develop methods for producing documentation 

2. Perform duties resulting from the development of these 
methods. For example: 

4D Use text processing with UNIX* DOCUMENTER'S 
WORKBENCH* (mm, nroff, tbl ) to: 

- Prepare documents and tables 

- Develop new macro commands 

e Serve as a point of contact for BCS with printers 

and distributors. 

3. If the job holder's interests and writing skills match 
the needs of the Technical Writing Staff, write 
documents . 



John Smith 



Copy to 

BCS Technical Writing Staff 



• Trademark of AT&T 
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9.8. Appendix H: Business Letter 

Input: 



•lO AT "Perscamel" 

.WA "Bill Taylor" "Director of Placement Services" 

Golunibia Uiiiversity 

116th Street 

Ifew York, NY 10019 

•WE 

.lO SA "Dear Dr. Shdth:" 

.lO FN "Career Day" 

.lA "Rebecca Stadth" 

Business Ccnpiter Systems, Inc. 

190 River Boulevard 

Durham, N.C. 27707 

.IE 

.LT BL 
.P 

We vculd be happy to include a representative of your oon?»ny in our 
"Career Day" program this spring . 

I am forwarding your request to James Blinn, who is organizing the event 

this year. 

.P 

Hhaadk you for ycur interest in our placement programs. 

.PC "Sincerely," 

.SG 

.NS 5 

.NE 

.NS 

J. Blinn 
.NE 
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Columbia University 
1 16th Street 
New York, NY 10019 
December 15, 1985 

In reference to: Career Day 



Rebecca Smith 

Business Computer Systems, Inc. 
190 River Boulevard 
Durham, N.C. 27707 

ATTENTION: Personnel 

Dear Dr. Smith: 

We would be happy to include a representative of your 
company in our "Career Day" program this spring. I am 
forwarding your request to James Blinn, who is organizing 
the event this year. 

Thank you for your interest in our placement programs. 



Sincerely , 



Bill Taylor 

Director of Placement Services 

JL-der 
Enc . 
Copy to 
J. Blinn 
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1. Introduction 



This is a technical discussion of tbl, a program that you use to produce 
simple and complex tables. Read this if you have had some experience with 
tbl; if you have never used tbl before, you should read the tutorial "The 
Preprocessor tbl*' in the User's Guide, 

Tables that you format with tbl consist of columns that you may center, 
right-adjust, left-adjust, or align according to digit and decimal point. You 
may place labels over single columns or groups of columns. A table entry 
may contain equations or consist of several rows of text. You may draw 
horizontal or vertical lines in the table, and you may enclose any table or 
element in a box. 
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2. Table Delimiters (.TS and .TE) 



Delimit tables with the macro pair .TS (table start) and .TE (table end), 
tbl processes certain commands (options, key letters, and commands specify- 
ing such details as point size and font control) that it finds between this 
macro pair, and it generates formatting requests, escape sequences, defined 
strings, and number registers. The .TS and ,TE lines are copied so that 
nroff/troff formatter layout macros (such as mm formatting macros) can use 
these lines as delimiters. The general format of a file that you would sub- 
mit to tbl is 




The format of each table is 




global options; 
format section, 
data 
.TE 
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Table Delimiters 

Each table is independent and contains 

■ Global options that affect the layout of the whole table 

■ A format section that describes individual columns and rows 
of the table 

■ Data that you want printed 

Unlike the options section, the format section and data are always required. 
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3. Global Options 



You may specify a single line of options to affect the layout of the 
whole table. These must be placed immediately after the .TS line. On this 
line, you must separate options with spaces, tabs, or commas. You must end 
the options line with a semicolon. Allowable options are 



center 


centers the table (default is left-adjusted) 


expand 


makes the table as wide as current line length 


box 


encloses the table in a box 


allbox 


encloses each data entry of the table in a box 


doublebox 


encloses the table in two boxes 


tab (x) 


separates data entries by using x instead of tab 


linesize (n) 


sets lines or rules (for example, from box) in n-point type 


delim {xx) 


recognizes x and x as eqn delimiters. 
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4. Format Section 



The format section of the table specifies the layout of the columns. Each 
line in the format section corresponds to one line of table data except the 
last format line, which corresponds to all following data lines up to any 
additional .T& command line. (.T& is described below.) Each format line 
contains a key letter for each column of the table. 



4.1. Key Letters 

In the format section, you may separate key letters with spaces or tabs to 
improve readability, but spaces or tabs are not necessary. A dot (•) indicates 
the end of key letters and should follow the last key letter before data is 
entered in the lines below. Key letters are 

L or 1 specifies a left-adjusted column entry 

R or r specifies a right-adjusted column entry 

C or c specifies a centered column entry 

N or n specifies a numerical column entry. Numerical entries are 
aligned according to digit and decimal point. 

A or a specifies an alphabetic subcolumn. All entries in an alphabetic 
subcolumn are aligned on the left and positioned so that the 
widest entry is centered within the column. 

S or s specifies a spanned heading. The entry from the previous 

column continues across this column. You may not use this key 
letter for the first column of a table. 

specifies a vertically spanned heading. The entry from the previ- 
ous row continues down through this row You may not use this 
key letter for the first row of a table. 

The layout of key letters in the format section resembles the layout of 
the data in the table. Thus, a simple 3-column format might appear as 

CSS 
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Format Section 



The first line of the table contains a heading centered across all three 
columns. Each remaining line of the table contains a left-adjusted item in 
the first column followed by two columns of numerical data, A sample 
table in this format is 



CENTERED HEADING 
Item-a 34.22 9.1 
Item-b 12.65 .02 
Item-c 23 5.8 
Total 69.87 14.92 

Instead of listing the format of successive lines of a table on consecutive 
lines of the format section, you may give successive line formats on the 
same line, separated by commas. That is, you can specify the format for the 
above example like this: 

CSS, Inn. 

Again, signal the end of the key letter section with a dot (. ). 

When you specify numerical column alignment («), tbl seeks a location 
for the decimal point. The rightmost dot (. ) adjacent to a digit is used as a 
decimal point. If there is no dot adjoining a digit, the rightmost digit is 
used as a units digit. If you do not specify alignment, the item is centered 
in the column. However, you may use the escape sequence \& (a zero- 
width character) to override dots and digits or to align alphabetic data. This 
aligns the dots, and the \& disappears from the final output. In the follow- 
ing example, the output column shows how items in the input column are 
aligned in a numerical column. 
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Format Section 



Input* 




.TS 














1 J 


4.2 


4.2 


26.4.12 


26.4.12 


abodefg 


abcjdefg 


abodN^Lefg 


abodefg 


abcdefgN& 


abcxiefg 


43\fi3.22 


433.22 


749.12 


749.12 


.TE 





If you use numerical data in the same column with wider L or r type 
table entries, tbl centers the widest number relative to the wider L or r 
items and preserves alignment within the numerical items. This is similar 
to the behavior of a type data. Alphabetic subcolumns (requested by the a 
key letter) are always slightly indented relative to L items. If necessary, the 
column width is increased to force this. This is not true for n type entries. 
You should not use n and a items in the same column. 



4.2. Additional Features 

Additional features of the key letter system are 

Horizontal lines 

You may replace a key letter by an underscore (_) to 
specify a horizontal line in place of the column entry, or 
an equal sign (=) to specify a double horizontal line. If 
an adjacent column contains a horizontal line or if there 
are vertical lines adjoining this column, the horizontal 
line extends to meet nearby lines. If you provide any 
data entry for a column containing an underscore or an 
equals sign, tbl ignores the entry and prints a warning 
message. 
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Format Section 

Vertical lines 

If you place a vertical bar (|) between column key letters, 
a vertical line appears between the corresponding 
columns of the table. A vertical bar to the left of the first 
key letter or to the right of the last one produces a line at 
the edge of the table. If two vertical bars appear between 
key letters, tbl draws a double vertical line. 

Space between columns 

You may follow a key letter with a number to show the 
amount of separation between this column and the next. 
The number specifies the separation in ens. One en is a 
relative measure about the width of the letter "n" in the 
current point size. More precisely, an en is the number 
of points (1 point = 1/72 inch) equal to half the current 
type size. If you use the expand global option, these 
numbers are multiplied by a constant so that the table is 
as wide as the current line length. The default column 
separation number is 3. If you change the separation 
number, the largest space requested prevails. 

Vertical spanning 

Vertically spanned entries extending over several rows of 
the table are centered in their vertical range. If you fol- 
low a key letter with t or T, any corresponding vertically 
spanned item begins at the top line of its range. 

Font changes 

You may specify that the corresponding column should 
be in a different font from the default font (usually 
roman) by following a key letter with the letter f or F 
and a character naming the desired font. You should put 
a space or a tab between a 1-letter font name and what- 
ever follows. The single letters B, h, I, and i are shorter 
synonyms for fB and fl. Font-change requests given 
with the data override these specifications. 

Point size changes 

You may specify the point size of the corresponding table 
entries by following a key letter with p or P and a 
number. If p or P is followed by an arithmetic expres- 
sion, such as +2, the formatter interprets it as an incre- 
ment (or decrement in the case of —2) from the current 
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Format Section 

point size. If you give both a point size and a column 
separation value, you must separate them with one or 
more blanks. 

Vertical spacing changes 

You may specify the vertical line spacing used within a 
multi-line data entry by following a key letter with v or 
V and a number. The formatter interprets an arithmetic 
expression (+2 or —2, for example) as an increment or 
decrement from the current vertical spacing. You must 
separate a column separation value by blanks or some 
other specification from a vertical spacing request. This 
request has no effect unless the corresponding data entry 
is a text block. 

Column width indication 

You may specify minimum column width by following a 
key letter with w or W and a width value in parentheses 
(for example, cw(5)). If the largest element in the column 
is not as wide as this specified width value, the formatter 
uses the width value to determine column size. If the 
largest element in the column is wider than the value 
you specify, the width of the largest element determines 
column width. 

The formatter also uses the width value as a default line 
length for included text blocks. You can use normal 
nroff/troff formatter dimensions, such as i, m, n, v, or u 
to scale the width value. (See the "nroff/troff Technical 
Discussion".) If you do not specify a scale, the formatter 
uses ens. If the width value is an unsealed integer, you 
may omit the parentheses. If you give another width 
value in a column, the last one you specify controls the 
width. 

Equal-width columns 

If you follow a key letter by e or E, you specify equal- 
width columns. The formatter makes all columns whose 
key letters are followed by e or E the same width. 

Staggered columns 

You may specify that the corresponding entry is to be 
moved up one-half line by following a key letter with u 
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Format Section 



or U. This makes it easy to have a column of differences 
between numbers in an adjoining column. The allbox 
option does not work with staggered columns. 

Zero-width item 

A key letter followed by z or Z specifies that the 
corresponding data item is to be ignored in calculating 
column widths. This may be useful in allowing headings 
to run across adjacent columns where spanned headings 
would be inappropriate. 

Default 

Column descriptors missing from the end of a format line 
are assumed to be L. That is, if you have more columns 
of data than descriptors to specify them, the data in the 
unspecified columns are left-justified. The longest line in 
the format section defines the number of columns in the 
table, tbl ignores columns in the data if there are not 
corresponding key letters in the format section. 

As some examples in the "tbl Sampler/' the features need not be 
separated by spaces except to avoid ambiguities involving point size and 
font changes. Thus, a numerical column entry in italic font and 12-point 
type with a minimum width of 2.5 inches and separated by 6 ens from the 
next column could be specified as 

ip12w(2.5i)fl 6 
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5. Data 



Put table data after the format section, typing each line of the table as 
one line of data. You may break a long input line into smaller lines by 
ending each short line, except the last, with a backslash. The resulting out- 
put line is as long as the combined parts. 

Data to be placed in different columns (data entries) should be separated 
with tabs or with whatever character you specify in the tab global option. 
There are a few special cases of data entries: 

nroff/troff commands within tables 

tbl assumes that an input line beginning with a dot is a 
request to the formatter and interprets it accordingly, 
retaining its position in the table. For example, a space 
within a table may be produced with the .sp request in 
the data. 

Full width horizontal lines 

tbl interprets a data line containing only the _ (under- 
score) character or =» (equal sign) to be a single or double 
line, respectively, extending the full width of the table. 

Single column horizontal lines 

tbl interprets a data entry containing only the _ character 
or the = to be a single or double line extending the full 
width of the column. Such lines extend to meet horizon- 
tal or vertical lines adjoining this column. To obtain 
these characters explicitly in a column, precede them 
with the escape sequence \&, or follow them with a space 
before the usual tab or newline character. 

Short horizontal lines 

A data entry containing only the string _^ is assumed to 
be a single line as wide as the contents of the column. It 
does not extend to meet adjoining lines. 

Repeated characters 

A data entry containing only a string of the form \Rx, 
where x is any character, is replaced by repetitions of the 
character x as wide as data in the column. The sequence 
does not extend to meet adjoining columns. 



tbh TECHNICAL DISCUSSION 1 1 



Data 



Vertically spanned entries 

A data entry containing only the escape sequence \* 
specifies that the data entry immediately above it spans 
downward over the corresponding row. It is equivalent 
to a table format key letter of 

Text blocks 

To include a block of text as a data entry, precede it by T{ 
and follow it by T). Thus, the sequence 

. . . T{ 

block of 

text 

T} . . . 

is a convenient method for inserting data not easily 
placed between tabs. You may put T{ (the beginning 
delimiter) anywhere in the data section. Do not put any 
character to the immediate right of this delimiter. You 
must put T) (the end delimiter) at the beginning of a 
line, and you may follow X} with a tab or tab character. 
You may follow the tab with additional columns of data 
on the same line. Table 4 in the "tbl Sampler" shows 
how to use text blocks. 

Text blocks are pulled out from the table, processed 
separately by the formatter, and replaced in the table as a 
solid block. Various limits in the nroff/troff program are 
likely to be exceeded if 30 or more text blocks are used in 
a table. This produces diagnostic messages such as Too 
nany text block diversions; tbl quits, Too nany 
string/nacro names, or Too many nunflDer registers. 

If no line length is specified in the block of text or in the 
table format, the default is to use 

L X C / (N + 1) 

where L is the current line length, C is the number of 
table columns spanned by the text, and N is the total 
columns in the table. 
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Data 



Other parameters (point size, font, and so on) that you 
may use in typesetting the text block are 

■ those in effect at the beginning of the table (includ- 
ing the effect of the .TS macro) 

■ any table format specifications of size, spacing, and 
font using the p, v, and f modifiers to the column 
key letters 

■ nroff/troff requests within the text block itself 
(requests within the data but not within the text 
block itself do not affect that block). 

Although you may put many lines in a table, tbl uses only the first 200 
lines to create the table. Similarly, column adjustment is determined for the 
first 200 lines only. You may arrange a multi-page table as several single- 
page tables if these limits prove to be a problem. 

When calculating column widths, tbl assumes that all data entries are in 
the font and size being used when the formatter encounters .TS. This is 
true except for font and size changes specified in the table format section 
(see Table 7 in the "tbl Sampler" or within the table data (as mentioned in 
the section "Data"). You may sprinkle nroff/troff requests throughout a 
table, but take care not to confuse tbl's width calculations. 
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6. Additional Command Lines 



To change the format of a single table, use the .T& (table continue) 
command. Such a table would look like this: 




global options ; 
format section , 
data 



new format section . 

data 

.T8. 



newer format section , 
data 




Using this procedure, each table line can be close to its corresponding 
format line. It is not possible to change the number of columns, the space 
between columns, the global options such as box, or the selection of 
columns to be made equal in width in additional command lines, tbl does 
not recognize this command after the first 200 lines of a table. 
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7. Using the tbl Command 



As the term "preprocessor" implies, you process a file with tbl before 
you run nroff or troff . On the UNIX system, the tbl program can process a 
simple table with the nroff commands 

tbl -TX file I nroff [option(s)] 
or 

mm -t [optionis)] file 

For troff output you can use 

tbl file I troff [option(s)] 
or 

mmt -t [option(s)] file 

When there are several input files containing tables, equations, pictures, and 
mm macro requests, type 

tbl -TX file! filel...\ neqn | nroff -mm 
For troff output type 

tbl -TX filel file!.., \ eqn | troff -mm 

The next section explains the rationale for placing tbl before eqn). 

Notice that you may specify options usually used with the nroff for- 
matter. Using nroff /troff is similar to using nroff. If you specify "-" as 
the file name, tbl reads the standard input at that point. 

The special -TX command-line option to tbl produces output without 
fractional line motions to accommodate line printers without adequate driv- 
ing tables or postprocessors. That is, this option tells tbl to process data in 
terms of full line motions. 
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Using the Ibl Command 



7.1. Equations in Tables 

When both tbl and eqn programs operate on the same file, you should 
call tbl first. If there are no equations within tables, either sequence works- 
It is usually faster to execute tbl first because eqn normally produces a 
larger expansion of the input. However, if you have equations within 
tables (using eqn's delim statement, see Table 5 in the "tbl Sampler"), you 
must execute tbl first, or the output will be scrambled. You should avoid 
use of eqn's equations in n-style (numeric) columns since tbl attempts to 
split numerical format items into two parts, and the delim (xx) statement 
prevents splitting numerical columns within delimiters. For example, if the 
eqn delimiters are $$, a delim ($$) statement causes a numerical column 
entry such as 

1245 $\(+. 16$ 

to be divided after 1245, not after 16. 



7.2. Using Number Registers 

The tbl program accepts up to 35 columns of data; this figure may be 
compromised depending on the availability of nroff /troff formatter number 
registers, tbl itself must define several macros and number registers. As a 
result, you must not use the following names for macros that you create: 
#f, #o, #+, #%, #&, and # . You must also avoid using number registers 
named by tbl. These include 2-digit numbers from 31 to 99 and strings of 
the form 4x, 5x, Ux, x+,x\, "x, and x-, where x is any lower-case letter. The 
register names ##, #-, #^ #T, and T# are also used by tbl in certain cir- 
cumstances. To conserve register names, the n and a key letters share a 
register; hence the restriction that you may not use them in the same 
column of the format section. 

As an aid in writing layout macros, tbl defines the number register TW, 
which is the table width, by the time that the .TE macro is invoked. You 
may use the register in the expansion of .TE. More important, to assist in 
laying out multi-page boxed tables, the macro T# is defined to produce the 
bottom lines and side lines of a boxed table and then to be invoked at its 
end. 
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Using the tbl Command 



You can print a multi-page boxed table with a repeated heading by giv- 
ing the argument H to the ,TS macro. If the table start macro is written 

.TS H 

then, a line of the form 
.TH 

must be given in the table after any table heading (or at the start if none). 
Material up to the .TH is placed at the top of each page of the table. The 
remaining lines in the table are placed on several pages as required. This is 
a feature of the mm macros, not of tbl. 
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8. tbl Sampler 



The following tables illustrate basic concepts of the tbl program. The 
<TAB> symbol in the input data represents a tab character produced by 
typing \t or by pressing the tab key. Although each table shows particular 
options or features, you may glean other information about usage from 
them. 

The following pages contain successive examples of matching input and 
output to provide models for making a variety of tables. The general format 
of the "tbl Sampler" is to show the contents of an input file, as read at a ter- 
minal, on the left page: 



option option option option ; 
key letter descriptor key letter descriptor 
key letter descriptor key letter descriptor 
key letter descriptor key letter descriptor 
key letter descriptor key letter descriptor , 
table heading data 

optional double or single horizontal line 
data entry <tna> data entry <tab> data entry 
optional double or single horizontal line 
data entry <tab> data entry <Tffl> data entry 
optional double or single horizontal line 
data entry <tmb> data entry <mb> data entry 



Input: 



,TS 
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. , tbl Sampler 

On the opposite right page, a corresponding example of output appears. 
Output: 



table headinfi data 


data entry 


data entry 


data entry 


data entry 


data entry 


data entry 


data entry 


data entry 


data entry 



The command line used for most of the examples below is as follows: 
tbl file I troff | phototypesetter 
Table 5 required 

tbl file I eqn | troff | phototypesetter 
in order to process the equations made with eqn. 
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Table 1: Using Horizontal Lines in Place of Key Letters 



Input: 



IB 



.TS 
box; 
L L L 
I* L ^ 
L L " 
L L _ 
L L L. 

janiazy <niB> febxuazy <imb> narch 
aprll <MB> nay 
june july <t*b> Months 
august <nB> septeniDer 
octc3ber <Ttt> no v caber <mB> decenber 
..IE 
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Output: 



January 


february 


march 


april 


may 






june 


july 


Months 


august 


September 






October 


november 


december 
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tbl Sampler 

Table 2: Changing Point Size of One Column 
Input: 



.TS 




c c 




np-2 ! 


n I . 


<TAB> 


Stadc 






1 <tAB> 46 


<TAB> 




2 <TAB> 


~23 


<TAB> 




3 <ttB> 


"l5 


<TAB> 




4 <TAB> 


'6.5 


<TAB> 




5 <TAB> 


"2.1 


<TAB> 




• TE 
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^ . tbl Sampler 

Output: 





Stack 


1 


46 


2 


23 


3 


15 


4 


6.5 


5 


2.1 
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tbl Sampler 

Table 3: Using Additional Command Lines 
Input: 




.TS 

box, center; 
c£3 s s s. 

Conpositicn of Foods 



c I c s s 

c ! c s s 

C I C I c I c. 

Food <TAB> Percent by Wfei^^t 

\" <TAB> 

\^ <T»D> Protein <mb> Eat <t*d> CsuAo- 
<TOB> \* <i»B> \'* <WB> hydrate 

1 I n I n I n. 

i^les <T»B> .4 <iaffl> ,5 <i»b> 13,0 
Halibut <TAB> 18.4 <i»b> 5.2 <na> . . . 
Lima beans <tab> 7.5 <^m> .8 <tab> 22.0 
MiUc <i»B> 3.3 <T»B> 4.0 <nB> 5.0 
MishnxDQs <TAB> 3.5 <tn3s> .4 <i»e> 6.0 
bread <»b> 9.0 <aa> .6 <t»b> 52.7 

y 
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Output: 



Composition of Foods 



Percent by Weight 



Food 


Protein 


Fat 


Carbo- 
hydrate 


Apples 


.4 


.5 


13.0 


Halibut 


18.4 


5.2 




Lima beans 


7.5 


.8 


22.0 


Milk 


3.3 


4.0 


5.0 


Mushrooms 


3.5 


.4 


6.0 


Rye bread 


9.0 


.6 


52.7 
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Table 4: Using Text Blocks and Controlling Column Width 
Input: 




.TS 

alUxBc; 
cf 2 s s 

cw(1i) cw(1.5i) cw(1,5i) 
111. 

New York Area Rocks 
.sp 

Era <TAB> Parmation <t»b> Age (years) 
Precairbrian <1!ab> Reading Proiig <T<ffl> >1 billion 
Paleozoic <tab> Manhattan Prong <iaffl> 400 ndllicn 

MeSOZOiC <TAB> T{ 

Nevark Basin, incl. 

Stocdrton , Lodcatcng , 

and Brunswick 

fomaticns 

T) <TAB> 200 million 

Cfenozoic <TAB> Coastal Plain <Tm> T{ 

On Long Island 

30,000 years; 

Cretaceous sediments 

redeposited 

by recent 

glaciation 
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Output: 



New York Area Rocks 



Era 


Formation 


Age (years) 


Precambrian 


Reading Prong 


> 1 billion 


Paleozoic 


Manhattan Prong 


400 million 


Mesozoic 


Newark Basin, incl, 
Stockton, Lockatong, 
and Brunswick forma- 
tions 


200 million 


Cenozoic 


Coastal Plain 


On Long Island 30,000 
years; Cretaceous sedi- 
ments redeposited by 
recent glaciation 
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Table 5: Including Equations 
Input: 



.BO 

delin S$ 

,m 

.TS 

doublebox; 
c c 
1 1. 

Name <o«> Definition 
•sp 

.vs +2p 

Gaana <i5w> SGAMIA (z)=intsubOsi9)iiif tsup {z-1} e sup -t dt$ 
Sine <WB> $sin (x) = 1 over 2i ( e ix - e sup -ix )$ 

Error $ ronan erf (2)= 2 over sqrt pi int sub sup z e si^ {-t sup 2} dt$ 
Bessel <T*B> SJ sub (2)= 1 over pi iut sub sup pi 00s (2 sin theta )d theta $ 
Zeta <i»B> $ 2eta (s) = sum from )c=1 to inf k sup -s — ( Re-s > 1)$ 
.vs -2p 
.sp 2p 
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Output: 



Name 


Definition 


Gamma 




Sine 




Error 




Bessel 


/o(2)=— f cos(2sintf)dfl 


Zeta 


(Res>l) 




jt-i 
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Table 6: Using Additional Command Lines and Defining Tab Character 
Input: 



.TS 

tab( 'CDffi> ); 
c s 
ci s 
1 n 
a n. 

Seme Lantiai Transport Statistics 
(Year 1964) 

Railvay route miles <ta8> 244 
TVobe <TAB> 66 
Sub-surface <tab> 22 
Surface <tnB> 156 
.sp .5 

1 r 
a r. 

Passenger traffic \- railway 
Journeys <tab> 674 million 
Average length <tab> 4.55 miles 
Passenger miles <tab> 3,066 million 

1 r 
a r. 

Passenger traffic \- road 
Journeys <tab> 2,252 million 
Average length <tab> 2.26 miles 
Passenger miles <tab> 5,094 millicn 

1 n 
a n. 
.sp .5 

Vehicles <xffl> 12,521 
Railway motor cars <t«> 2,905 
Railway trailer cars <tab> 1,269 
Ibtal railway <tab> 4,174 
Qraiibuses <tab> 8,347 
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Output: 



Some London Transport Statistics 
(Year 1964) 

Railway route miles 24 

Tube 6 

Sub-surface 2 

Surface 15 

Passenger traffic - railway 



Journeys 



Average length 
Passenger miles 



674 million 
4.55 miles 
3,066 million 



Passenger traffic — road 



2,252 million 
2.26 miles 
5,094 million 



Journeys 



Average length 
Passenger miles 



Vehicles 

Railway motor cars 
Railway trailer cars 
Total railway 
Omnibuses 



12,521 
2,905 
1,269 
4,174 
8,347 
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Table 7: Using Different Point Sizes and Column Widths 
Input: 



.TS 

box tab( <nB> ) ; 



Ciclcs 

ltiw( 1i)lltw(1.5i)p8!lpellw(1.5i)p8. 
Sore Interesting Places 

Name <tab> Descxipticn <wb> Practical Infacnaticn 
T{ 

Anerican Miseum 
of Natural History 
T} <»B> T{ 

•Die collections fill 11.5 acres 

(Michelin) car 25 acres (MTA) 

of exhibition halls on 

four floors. Olhere is a full-sized 

replica of a blue vihale and the 

vcrld's largest star sapfiiire 

(stolen in 1964). 

T} <UB> Hours <UiB> 10-5, ex. Sun 11-5, Wfed. to 9 

V <T«> X'' <i5ffi> Location <wb> t{ 
Central Park West & 79th St. 

T} 

V <TMB> V <isffi> Afadssion <i!m> Donation: $1.00 asked 

V <TAB> V <MB> Subway <tab> AA to 81st St. 
\* <T*B> \^ <WB> Telephone <»b> 212-873-4225 

Bronx Zoo <ttB> T{ 
About a mile Icng and .6 mile 
wide, this is the largest zoo in 
Anerica. A lion eats 18 
pounds of meat a day while a 
sea lion eats 15 pounSs of fish. 
V T) <TS(B> Hours <Tiffl> T{ 
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Input Cont'd: 



10-4:30 winter, to 5:00 suniner 
T} 

V <TAB> V <TAB> Location <TAD> T{ 

185th St. & Soathem Blvd, the Bronx. 
T) 

V <M> V <TAff> Atoission <s§s> $1,00, but Ta.We.lh free 
\^ <fMa> \" <i»B> Subway <»d> 2, 5 to East Tranont Ave. 

V <T*B> \^ <T«> Teleplione <tab> 212-933-1759 

Brooklyn Maseim <tab> T{ 

Five floors of galleries contain 

Anerican and ancient art. 

Ohere are American period 

rocos and architectural amaroents 

saved fron wreckers, 

such as a classical figure from 

Pennsylvania 

Station. 

T} <i»B> Hours <T*B> Wed-Sat, 10-5, Sun 12-5 

V <«B> \^ <Tiffi> Location <wb> T{ 
Eastern Fkway & Washington Ave. 
Brooklyn. 

T) 

\* <TOB> \^ <T»B> Ainission <»b> Rree 

V <TAB> V <TAB> Subway <i»b> 2,3 to Eastern Parkway. 
\^ \^ <TOB> Telephone <tab> 212-639-5000 

T{ 

New York 

Historical Society 

T} <T»B> T{ 

All the original paintings for 

Ajdubon's 

.1 

Birds of Anerica 
.R 
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Input Cont'd: 



are here, as are esdiibits of American 
deoorative arts, New York 
history, Hudson River sctool 
paintings, carriages, and glass 
paperweights. 

T} <TAB> Hours <1!AB> T{ 

TUes-Rci & Sun, 1-5; Sat 10-5 
T} 

\^ <1SAB> \^ <TAB> Location <T(ffi> T{ 

central Park West & 77th St. 
T} 

X'' <TAB> \^ <TAa> Acbdssion <uib> Free 
V <TM> V <TAB> Subway <m8> AA to 81st St. 
&.\" <cnB> \^ <TAB> Telephone <t*b> 212-873-3400 
.TE 
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tbl Sampler 



Output: 



Some Interesting Places 


Name 


Description 


Practical Information 


American Museum 
of Natural History 


The collections fill 11.5 acres 
(Michelin) or 25 acres (MTA) 
of exhibition halls on four 
floors. There is a full-sized 
replica of a blue whale and 
the world's largest star sap- 
phire (stolen in 1964). 


Hours 

LiOCallOn 

Admission 

Subway 

Telephone 


10-5, ex. Sun 11-5, Wed. to 9 

V-cniial 1 ails, WtrSl OC /7in 31. 

Donation: $1.00 asked 
AA to 81st St. 
212-873-4225 


Bronx Zoo 


About a mile long and .6 
mile wide, this is the largest 
zoo in America. A lion eats 
18 pounds of meat a day 
while a sea lion eats 15 
pounds of fish. 


Hours 

Location 

Admission 

Subway 

Telephone 


10-4:30 winter, to 5:00 sum- 
mer 

185th St. & Southern Blvd, 
the Bronx. 

$1.00, but Tu,We,Th free 
2, 5 to East Tremont Ave. 
212-933-1759 


Brooklyn Museum 


Five floors of galleries con- 
tain American and ancient 
art. There are American 
period rooms and architec- 
tural ornaments saved from 
wreckers, such as a classical 
figure from Pennsylvania 
Station. 


Hours 
Location 

Admission 

Subway 

Telephone 


Wed-Sat, 10-5, Sun 12-5 
Eastern Pkway & Washing- 
ton Ave. Brooklyn. 

Free 

2,3 to Eastern Parkway. 
212-638-5000 


New York Historical 
Society 


All the original paintings for 
Audubon's Birds of America 
are here, as are exhibits of 
American decorative arts. 
New York history, Hudson 
River school paintings, car- 
riages, and glass paper- 
weights. 


Hours 

Location 

Admission 

Subway 

Telephone 


Tues-Fri & Sun, 1-5; Sat 10-5 
Central Park West & 77th St. 
Free 

AA to 81st St. 
212-873-3400 
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Introduction 



nroff and troff are text processors provided with the UNIX System V 
DOCUMENTER'S WORKBENCH Software. They accept lines of text inter- 
spersed with lines of format control information and process the text into a 
printable, paginated document having a user-designed style, nroff and 
troff offer unusual freedom in document styling, including the following: 
arbitrary style headers and footers; arbitrary style footnotes; multiple 
automatic sequence numbering for paragraphs, sections, and other user- 
defined blocks of text; multiple column output; dynamic font and point-size 
control; arbitrary horizontal and vertical local motions; and a group of 
automatic overstriking, bracket construction, and line drawing functions. 

nroff and troff are highly compatible with each other, and it is almost 
always possible to prepare input acceptable to both. Conditional input is 
provided that enables the user to embed input expressly destined for either 
program, troff formats text suitable for phototypesetters and printers capa- 
ble of producing digital-typographical output. 

The general form of invoking nroff or troff at the UNIX system com- 
mand level is 

nroff option(s) file(s) \printer 
or 

troff option(s) file(s) \ typesetter 

where optiorj(s) represents any of a number of options and option argu- 
ments, and file(s) represents the file containing the document to be format- 
ted. An argument consisting of a single minus (— ) is taken to be a file name 
corresponding to the standard input. If no file is given, input is taken from 
the standard input. The options, which may appear in any order so long as 
they appear before the file name(s), are 

Option Effect 

-e (nroff only.) Produce equally-spaced words in adjusted 

lines, using full terminal resolution. 

— h (nroff only.) Use output tabs during horizontal spacing 

to speed up output as well as to reduce output byte 
count. Device tab settings are assumed to be every 8 
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nominal character widths, as are the settings of input 
(logical) tabs. 

Read standard input after the input files are exhausted. 

Prepend the macro file /usr/lib/tmac.wflm^ to the input 
files, nroff and troff can accept several -m options on 
the command line causing all macro packages thus 
named to be read in turn. The possible macro packages 
(the memorandum macros, the man macros, the view- 
graph macros, and the permuted index macros) would be 
called, with the following options, respectively: —mm, 
-man, -mv, and -mptx. 

Number first generated page N. 

Print only pages whose page numbers appear in list, list 
consists of comma-separated numbers and number 
ranges. A number range has the form N—M and means 
pages N through M; an initial —N means from the begin- 
ning to page N; and a final N— means from N to the end. 

Invoke the simultaneous input-output mode of the .rd 
request. 

Set the number register whose (one-character) name is a 
to N. 

Stop every N pages, nroff will halt prior to every N 
pages (default N=l) to allow paper loading or changing, 
and will resume upon receipt of a new-line, troff will 
stop the phototypesetter every N pages, produce a trailer 
to allow for changing of paper, and will resume after the 
phototypesetter START button is pressed. In nroff the 
ASCII BEL character will sound when stopping between 
pages. 
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—Tttyjype Specifies the name of nroff terminal type, ttyjype. 
Currently defined names are 

2631 Hewlett-Packard 2631 printer in regular mode 
2631-c Hewlett-Packard 2631 printer in compressed 
mode 

2631-e Hewlett-Packard 2631 printer in expanded mode 
300 DASI-300 printer 

300-12 DASI-300 terminal set to 12-pitch (12 characters 
per inch) 

300s DASI-300S printer (300S is a synonym) 
300S-12 DASI-300S printer set to 12-pitch (12 characters 

per inch) (3005-12 is a synonym) 
37 Teletype Model 37 terminal (default) 

382 DTC-382 

4000a Trendata 4000a terminal (4000A is a synonym) 
450 DASI-450 (Diablo Hyterm) printer 
450-12 DASI-450 terminal set to 12-pitch (12 characters 
per inch) 

832 Anderson Jacobson 832 terminal 
8510 C.ITOH printer 

Ip generic name for printers that can underline 

and tab. (All text using reverse linefeeds, such 
as those having tables, that is sent to Ip must be 
processed with col.) 
tn300 GE Terminet 300 terminal 
X printers equipped with TX print train 

(Check with your system administrator for a list of 
locally supported devices.) 

In troff, the -T option may be used to specify the output 
device. In addition, it is possible to set the environment 
variable "TYPESETTER." The output devices presently sup- 
ported for troff are the Autologic APS-5 (—Taps) and the 
Imagen Imprint-10 (— TilO) 

— uiV (nroff only.) Set the emboldening strike-count (number 

of character overstrikes) for the bold font (normally 
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Introduction 



mounted at the third font position) to be N. If option is 
used without N, the number of overstrikes is assumed to 
be zero. Note that it is not possible to turn off the 
emboldening in nroff if the overstriking is controlled 
locally by the printing device (e. g., DASI 300s). See the 
•bd request in Section 2.3 and the .b number register in 
Section 4 for a fuller treatment of emboldening. 

"Z Suppress formatted output. Only diagnostics and mes- 

sages from 4111 requests will occur. 

"■a Send a printable ASCII approximation of results to the 

standard output. 

Each option is invoked as a separate argument; for example, 

nroff -o4,8-10 -T300-12 -mabc filel file2 

requests formatting of pages 4, 8, 9, and 10 of the document contained in 
files named filel and file2, specifies the output terminal as a DASI 300 in 
12-pitch, and invokes the macro package abc. 

Various pre- and postprocessors are available for use with nroff and 
tro£f. These include the preprocessors for writing equations, neqn and 
eqn (for nroff and troff respectively); the preprocessor for making 
tables, tbl; the preprocessor for drawing pictures, pic, and the grap 
preprocessor for presenting statistics in a graph. A reverse-line post- 
processor, col, is available for multiple-column nroff output on terminals 
without reverse-line ability; col expects the Teletype Model 37 escape 
sequences that nroff produces by default, troff output can be viewed on 
the Teletype Model 5620. No special filter is required to postprocess 
troff's output for the 5620. The finished version of a document typeset 
with troff is most frequently sent to a phototypesetter: 

grap file(s) \ pic | tbl | eqn | troff option(s) \ typesetter 

The first pipe (| ) indicates the redirecting of grap's output to pic's input; 
the second pipe shows pic's output being redirected to tbl's input; the 
third pipe shows tbl's output flowing into eqn's input; the fourth indi- 
cates the piping of eqn's output to troff's input. Finally, the accumu- 
lated output from these processes is piped to a postprocessor that inter- 
prets troff's output graphics language for the output device. 
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, Introduction 

tc is a phototypesetter-simulator postprocessor, which enables you to 
view troff output on a Tektronix 4014 terminal. The syntax for its usage 
is as follows: 

grap file(s) \ pic | tbl | eqn | troff option(s) \ tc 

The remainder of this manual consists of a "Summary" followed by 
"A Technical Description of nroff/troff The numbered sections of the 
"Summary" correspond to numbered sections of the "Technical Descrip- 
tion/' in which the individual nroff/troff subcomponents are covered in 
detail. 



nroff/troff: TECHNICAL DISCUSSION 5 



Summary 



This summary presents abstracts of requests, escape sequences, number 
registers, and predefined strings. It gives essential information about these 
subcomponents such as syntax usage, value of arguments, and default scal- 
ing of parameters. The following is a key to some of the notation: 

Notes: 

B Request normally causes a break. 

D Mode or relevant parameters associated with current diversion 
level. 

E Relevant parameters are a part of the current environment, 
O Must stay in effect until logical output. 

P Mode must be still or again in effect at the time of physical out- 
put. 

T Parameters are typesetter- or printer-dependent. 
v,p,m,u Default scale indicator; if not specified, scale indicators are 
ignored. 

; Values separated by ";" are for nroff and troff respectively. 

t Requests marked with "f" have no effect in nroff. 

f Requests marked with cause a line break, like that caused by 

.br. Invoking them with the control character (instead of ".") 

will suppress that break function. 



1. General Explanation 



{This topic is covered in section 1 of the ''Technical Description'' below,) 



2. Font and Character Size Control 

Notes Explanation 



Request 
Form 

.ps±N 
.ss N 



Initial 
Value 

lOpoint 
1^/36 em 



xsFNM off 



If No 
Argument 

previous E.f Point size; also \s±N. 
ignored E,t Space-character size set to 
N/36 em. 

P,t Constant character space (width) 
mode (font F), 
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Summary 



.bd FN off 
.hdS FN off 



.ft F 

ApN F 



Roman 



P Embolden font F by N-1 units, 
P Embolden Special Font when 
current font is F. 
previous E,T Change to font F = x, xx, or l-N. 

Also \fxAHxxAfN. 
ignored T Font named F mounted on phy- 
sical position KN. 



3. Page 


Control 




Request 
Form 


Initial 
Value 


If No 
Argument 


.pl±N 
,bp ±N 


llin 
N=l 


llin 


.pn ±N 
.po ±N 
.neN 


/s/=l 

0; 26/27 in 


ignored 

previous 

N^IV 


.mk R 


none 


internal 


.rt ±N 


none 


internal 



Notes Explanation 

V Page length. 

B4,v Eject current page; next page 
number N. 

Next page number N. 

V Page offset. 

D,v Need N vertical space {V = vert- 
ical spacing). 

D Mark current vertical place in 
register R, 

D,v Return (upward only) to marked 
vertical place. 



4. Text 


Filling, 


Adjusting, 


Request 


Initial 


If No 


Form 


Value 


Argument 


.br 






.fi 


fill 




.nf 


Hll 




.ad c 


adj,both 


adjust 


.na 


adjust 




.ce N 


off 





and Centering 

Notes Explanation 

B4 Break. 
B4,E Fill output lines, 
B4,E No filling or adjusting of output 
lines. 

E Adjust output lines with mode c. 
E No output line adjusting. 
B4,E Center following N input text 
lines. 
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5. Vertical Spacing 

Request Initial If No 



Form Value Argument 

•vs N l/6in;12pts previous 

.Is N N— 1 previous 

.spN - 

•svN - N=1V 

.OS 

.ns space 

.rs - 



Notes Explanation 

E,p Vertical base line spacing (V). 
E Output N— 1 Vs after each text 

output line. 
B4/V Space vertical distance N in 

either direction. 
V Save vertical distance N, 

Output saved vertical distance. 
D Turn no-space mode on. 
D Restore spacing; turn no-space 

mode off. 



6. Line Length and Indenting 

Request Initial If No Notes Explanation 

Form Value Argument 

.11 ±N 6.5 in previous E,m Line length. 

.in ±N N=0 previous B4,E,m Indent. 

M ±N - ignored B4,E,m Temporary indent. 



7. Macros, Strings, Diversion, and Position Traps 



Request Initial 


If No 


Notes Explanation 


Form Value 


Argument 




.de XX yy 


.yy^.. 


Define or redefine macro xx; end 






at call of yy. 


.am XX yy 




Append to a macro. 


As XX string - 


ignored 


Define a string xx containing 






string. 


.as XX string • 


ignored 


Append string to string xx. 


.rm XX 


ignored 


Remove request, macro, or 






string. 
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Summary 



• Alt 


ignored 




Rename request, macro, or string 








XX to yy. 


.di XX 


end 


D 


Divert output to macro xx. 


.da XX 


end 


D 


Divert and append to xx. 


.wh N XX 




V 


Set location trap; negative is 








with respect to page bottom. 


.ch XX N 




V 




.dt N XX 


off 




Set a diversion trap. 


.it N XX 


off 


E 


Set an input-line count trap. 


.em XX none 


none 




End macro is xx. 


8. Number Registers 






Request Initial 


If No 


Notes Explanation 


Form Value 


Argument 






.nr R ±N M- 




u 


Define and set number register 








R; auto-increment by M. 


.af R c Arabic 






Assign format to register R (c=l. 








i/ I. a. A). 


.rr R 






Remove register R. 



9. Tabs, Leaders, and Fields 



Request 


Initial 


If No 


Notes Explanation 


Form 


Value 


Argument 




.ta Nl ... 


0.8;0.5in 


none 


E,m Tab settings; left type, unless 
f=R (right) or f=C (centered). 


.tc c 


none 


none 


E Tab repetition character. 


Acc 




none 


E Leader repetition character. 


.fc a b 


off 


off 


Set field delimiter a and pad 
character b. 
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Summary 



10. Input and Output Conventions and Character 
Translations 



Request 


Initial 


If No 


Notes Explanation 


Form 


Value 


Argument 






•ec c 


\ 


\ 




Set escape character. 


.eo 


on 






Turn off escape character 










mechanism. 




-;on 


on 




Ligature mode on if N>0. 


.ul N 


off 




E 


Underline (italicize in troff) N 


•cu N 








input lines. 


off 




E 


Continuous underline in nroff; 










like .ul in troff. 


.uf F 


Italic 


Italic 




Underline font set to F (to be 










switched to by .ul). 


•cc c 






E 


Set control character to c. 


.c2c 






E 


Set no-break control character to 


•tr abed.... 


none 




O 


c. 

Translate a to b, etc., on output. 



11. Local Horizontal and Vertical Motions, and the 
Width Function 



Vertical 
Motion 


Effect in 
troff nroff 


Horizontal 
Motion 


Effect in 
troff nroff 


WN' 


Move distance N 


\h'N' 
\(space) 

\o 


Move distance N 
Unpaddable space-size space 
Digit-size space 


\u 
\d 
\r 


V5 em up 

em down 
1 em up 


line up 
line down 
1 line up 


\| 
\- 


1/6 em space 
1/12 em space 


ignored 
ignored 
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12. Overstrike, Bracket, Line-drawing, and Zero- 
width Functions 



Function 



Automatically centered overstriking of characters named 
in string. 



Zero-width spacing following character c to produce 
overstruck characters. 



Vertically pile characters named in string. 



Horizontal line drawing function. Optional character c 
may be named to travel to the right a distance N, Travel 
to the left may be specified with a negative N. 



Vertical line drawing function. Optional character c 

may be specified to travel downward a distance N. Upward 

distance may be specified with a negative N. 



13. Hyphenation 



Request 
Form 

•nh 
.hy N 
.he c 

.hw wordl 



Initial 
Value 

no hyphen 
no hyphen 



If No 
Argument 

hyphenate 

\% 

ignored 



Notes Explanation 

E No hyphenation. 

E Hyphenate; N = mode. 

E Hyphenation indicator character 

c. 

Exception words. 



14. Three Part Titles 



Request 
Form 



Initial 
Value 



.11 'lefi'center'right' 
•pc c % 
.It ±N 6.5 in 



If No 
Argument 

off 

previous 



Notes Explanation 



E,m 



Three part title. 

Page number character. 

Length of title. 
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Summary 



15. Output Line Numbering 

Request Initial If No Notes Explanation 

Form Value Argument 

•nm ±N M S I off E Number mode on or off, set 

parameters. 

•nn N - N-l E Do not number next N lines. 



16. Conditional Acceptance off Input 



Request Initial 
Form Value 

.if c anything- 



If No Notes Explana tion 
Argument 



.if !c anything 

.if N anything 

.if !N anything 

.if 'stringV string!' anything 

At I 'string! 'string!' anything 

.ie c anything 

.el anything 



If condition c true, accept anything as 
input, for multi-line use \[any- 
thing\]. 

If condition c false, accept any- 
thing. 

If expression N > 0, accept any- 
thing. 

If expression N < 0, accept any- 

If stringl identical to string!, 
accept anything. 

If stringl not identical to string!, 
accept anything. 
If portion of if-else; all above 
forms (like if). 
Else portion of if-else. 
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17. Environment Switching 



Request Initial If No Notes Explanation 

Form Value Argument 

.ev N N=0 previous - Environment switched (push 

down). 

18. Insertions from the Standard Input 

Request Initial If No Notes Explanation 

Form Value Argument 

.rd prompt - prompt^BEL - Read insertion. 

,ex - - - Exit from nroff/troff. 

19. Input/Output File Switching 

Request Initial If No Notes Explanation 

Form Value Argument 

.so file - - - Switch source file (push down), 

.nx file - end-of-file - Next file, 

.cf file - - - Copy file. 

.If N file - - - change line number and file 

name. 

.pi program - - Pipe output to program. 

20. Miscellaneous 

Request Initial If No Notes Explanation 

Form Value Argument 

.mc c N ' off E,m Set margin character c and 

separation N. 

.tm string - new-line - Print string on terminal (UNIX 

standard message output), 
.ig yy - .yy-^.. - Ignore till call of yy. 
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Print macro names and sizes; 
if t present print only total of 
sizes. 

Flush output buffer. 
Terminates processing immedi- 
ately. 

cmd executed but output not 
captured. 

21. Output and Error Messages 

{This topic is covered in section 21 of the 'Technical Description" which fol- 
lows.) 



22. Request and Section Number Cross Reference 



.ab 20 


.c2 10 


.de 7 


.ev 17 


.hwl3 


.If 19 


.ne 3 


.OS 5 


.rd 18 


.SS 


2 


.tr 10 


.ad 


4 


.cc 10 


.di 7 


.ex 18 


.hyl3 


.Ig 10 


.nf 4 


.pc 14 


.rm 7 


.sv 


5 


.uf 10 


.af 


8 


.ce 4 


.ds 7 


.fc 9 


.ie 16 


.11 6 


.nhl3 


.pi 19 


.rn 7 


.sy 


20 


.ul 10 


.am 


7 


.cf 19 


.dt 7 


.fi 4 


.if 16 


.Is 5 


.nml5 


.pi 3 


.rr 8 


.ta 


9 


.vs 5 


.as 


7 


,ch 7 


.ec 10 


.fl 20 


.ig 20 


.It 14 


.nn 15 


.pm20 


.rs 5 


.tc 


9 


.wh 7 


.bd 


2 


.cs 2 


.el 16 


.fp 2 


.in 6 


.mc20 


.nr 8 


.pn 3 


.rt 3 


.ti 


6 




.bp 


3 


.cu 10 


.em 7 


.ft 2 


.it 7 


.mk 3 


.ns 5 


.po 3 


.SO 19 


.tl 


14 




.br 


4 


.da 7 


.eo 10 


.he 13 


.Ic 9 


.na 4 


.nx 19 


.ps 2 


.sp 5 


.tm20 





.pm / - all - 

.fl . - B4 

.ab text - user abort - 

.sy cmd args - 
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23. Escape Sequences for Characters, Indicators, 
and Functions 



Section 


Escape 


Meaning 


Reference 


Sequence 




10.1 


W 


\ (to prevent or delay the interpretatior\ of \ ) 


10.1 


\e 


rnntaDle version ot trie current escape cnaracier. 


2.1 


\ 


^acute accent, lypograpnicaiiy cLjuivaiciu lu \\aa/ 


2.1 


\ 


^grave accent, typograpnicaiiy equivaieiii lu 






\(ga) 


2.1 


\- 


— (minus sign in the current font) 


7.2 


V 


. (period or dot; see .de) 


11.1 


\(space) 


Unpaddable space-size space character 


11.1 


\o 


Digit width space 


11.1 


\l 


l/6em narrow space character (zero width in 






nroff) 


11.1 


\* 


1/12 em half-narrow space character (zero width 






in nrorr) 


4.1 




Non-printing, zero width character 


10.6 


V 


Transparent line indicator 


10.7 


A" 


Beginning of comment 


7.3 


\$N 


Interpret argument l^iV^9 


13 


\% 


Default optional hyphenation character 


2.1 


\(xx 


Character named xx 


7.1 


\*x, \*(xx 


Interpret string x or xx 


9.1 


\a 


Non-interpreted leader character 


12.3 


\b'abc...' 


Bracket building function 


4.2 


\c 


Interrupt text processing 


11.1 


\d 


Forward (down) 1/2 em vertical motion (1/2 line 






in nroff) 


12.4 


\D 


Line-drawing functions 


2.2 


\fxAf(xxAfN 


Change to font named x or xx, or position N 


8 


\SX, \s(xx 


Return the format of values stored in general 




number registers x and xx. 


11.1 


\h'N' 


Local horizontal motion; move right N (negative 






left) 


2.3 


\H'N' 


Height control of characters (does not affect 



width). 
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11.3 \kx Mark horizontal input place in register x 

12.4 \l'Nc' Horizontal line drawing function (optionally 

with c) 

12.4 \L'Nc' Vertical line drawing function (optionally with c) 

8 \n;rAn(xx Evaluate number register x or xx 

12.1 \o'abc...' Overstrike characters a, b, c, ... 

41 \p Break and spread output line 

II 1 V Reverse (up) lem vertical motion (reverse line in 

nroff) 

2.3 \sNAs±N Point-size change function 

2.3 \S'w' Slant control of characters. 

9.1 \t Non-interpreted horizontal tab 

III \« Reverse (up) 1/2 em vertical motion (1/2 line in 

nroff) 

11.1 \v'N ' Local vertical motion; move down JV (negative 

up) 

11.2 \w'$trmg ' Evaluate and use width of string 

5.2 \xW ' Extra line-space function (negative before, posi- 

tive after) 

12.2 \zc Print c with zero width (without spacing) 

16 \{ Begin conditional input 

16 \} End conditional input 

10.7 \(new-line) Concealed (ignored) new-line 

\C C any character not listed above 

The escape sequences W \., V, \$, \», \a, \n, \t, and \(new-line) are inter- 
preted in copy mode. 
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Summary 



24. Predefined General Number Registers 

Section Register Description 
Reference Name 



J 




Current page number. 






Emboldening factor of current font. 






Input line-number in the current input file. (Con- 






tains the same value as the read-only .c register.) 




•R 


Count of number registers that remain available 






for use. 


11.2 


ct 


Character type (set by width function),vail 


7.4 


dl 


Width (maximum) of last completed diversion. 


7.4 


dn 


Height (vertical size) of last completed diversion. 




dw 


Current day of the week (1-7). 




dy 


Current day of the month (1-31). 


15 


In 


Output line number. 




mo 


Current month (1-12). 


4.1 


nl 


Vertical position of last printed text base-line. 


11.2 


sb 


Depth of string below base line (generated by 






width function). 


11.2 


St 


Height of string above base line (generated by 






width function). 




y 


Last two digits of current year. 


25. Predefined Read-only Number Registers 


Section 


Register 


Description 


Reference 


Name 




7.3 


.$ 


Number of arguments available at the current 






macro level. 




$$ 


Identification number (process i.d.) for nroff or 






troff processes. 




.A 


Set to 1 in troff if -a option used; always 1 in 






nroff. 




.F 


string that is the name of the current input file. 


11.1 


.H 


Available horizontal resolution in basic units. 




.L 


Current line-spacing parameter (see request, .Is). 
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Set to 1 if the current page is being printed, and 
zero otherwise. 

Set to 1 if -T option used; otherwise set to 0. 
Available vertical resolution in basic units. 
Post-line extra line-space most recently utilized 
using \x'N'. 

Number of lines read from current input file. 

Current vertical place in current diversion; equal 

to nl, if no diversion. 

Current font as numerical position. 

Text base-line high-water mark on current page 

or diversion. 



6 .1 Current indent. 

•j Current adjustment mode and type. Can be saved 

and later given to the .ad request to restore a pre- 
vious mode. 

Horizontal size of the text portion (without 
indent) of the current partially collected output 
line, if any, in the current environment. 
^ •! Current line length. 

^•1 Length of text portion on previous output line. 

^ -o Current page offset. 

3 .p Current page length. 

2.3 .s Current point size. 

7-5 A Distance to the next trap. 

^ '^ Equal to 1 in fill mode and in no-fill mode. 

51 .v Current vertical line spacing. 

11-2 .w Width of previous character. 

•X Reserved version-dependent register. 

•y Reserved version-dependent register. 

'^•^ ♦z Name of current diversion. 



26. Predefined Strings 

T Name of output device. 
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A Technical Description of nroff/ troff 

This section explains the subcomponents listed in the summary. The 
subcomponents can be cross-referenced by section number. 

1. General Explanation 



1.1. Form of Input 

Input consists of text lines, which are destined to be printed, inter- 
spersed with control lines, which set parameters or otherwise control subse- 
quent processing. Control lines begin with a control character— normally a 
period (.)/ or an acute accent (') followed by a one or two character name 
that specifies a basic request or the substitution of a user-defined macro in 
place of the control line. The control character suppresses the break 
function— the forced output of a partially filled line— caused by certain 
requests. The control character may be separated from the request or macro 
name by white space (spaces and /or tabs) for aesthetic reasons. Names must 
be followed by either space or a new-line. Control lines with unrecognized 
names are ignored. 

Various special functions may be introduced anywhere in the input by 
means of an escape character, normally \. For example, the function \nR 
invokes the contents of the number register R in place of the function; here 
R is either a single character name as in \nx, or a left-parenthesis- 
introduced, two-character name as in \n(xx. 

1.2. Formatter and Device Resolution 

nroff internally uses 240 units/inch, corresponding to the least common 
multiple of the horizontal and vertical resolutions of various current 
typewriter-like output devices. Units in troff are device-dependent, troff 
rounds horizontal/vertical numerical parameter input to its internal 
horizontal/vertical resolution, nroff similarly rounds numerical input to the 
actual resolution of the output device indicated by the -T option (default 
Teletype Model 37). 
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Description 



1.3. Numerical Parameter Input 

Both nroff and troff accept numerical input with the appended scale 
indicators shown in the following table, where S is the current type size in 
points, V is the current vertical line spacing in basic units, and C is a nomi- 
nal character width in basic units. 



Scale 




Number of Basic Units 


Indicator 


Meaning 


troff 


nroff 


i 


Inch 




240 


c 


Centimeter 




240x50/127 


P 


Pica - 1/6 inch 




240/6 


m 


Em — S points 


machine- 


C 


n 


En - Em/2 


dependent 


C, same as Em 


P 


Point =J/72 inch 




240/72 


u 


Basic unit 




1 


V 


Va^cal line space 




V 


none 


Default, see below 







In nro£f, both the em and the en are taken to be equal to the C, which is 
output-device dependent; frequent values are 1/10 and 1/12 inch. Actual 
character widths in nroff need not be all the same, and characters con- 
structed with predefined strings such as -> (— ) are often extra wide. 

The scaling for horizontally-oriented control characters, vertically- 
oriented control characters, and the requests .nr, .if, and Je are as follows: 



Orientation 


Measure by Default 


Request or Function 


Horizontal 


Em (m) 


.11, .in, .ti, .ta, .It, .po, 
.mc, \h, \1. 


Vertical 


Vertical line space (v) 


.pi, .wh, .ch, .dt, .sp, ,sv, 
.ne, -rt, \v, \x, \L 


Register-oriented 
or conditional 


Basic unit (u) 


.nr, .if, .ie. 


Miscellaneous 


Point (p) 


.ps, .vs, \H, \s. 



All other requests ignore any scale indicators. When a number register con- 
taining an already appropriately scaled number is interpreted to provide 
numerical input, the unit scale indicator u may need to be appended to 
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— Description 

prevent an additional inappropriate default scaling. The number, N, may 
be specified in decimal-fraction form but the parameter finally stored is 
rounded to an integer number of basic units. 

The absolute position indicator I may be prepended to a number N to 
generate the distance to the vertical or horizontal place N, For vertically- 
oriented requests and functions, IN becomes the distance in basic units from 
the current vertical place on the page or in a diversion to the the vertical 
place N. (See section 7.4, "Diversions.") For all other requests and func- 
tions, I N becomes the distance from the current horizontal place on the 
input line to the horizontal place N. For example, 

.sp 13.2c 

will space in the required direction to 3.2 centimeters from the top of the 
page. 



1.4. Numerical Expressions 

Wherever numerical input is expected an expression involving 
parentheses, the arithmetic operators +, /, % (mod), and the logical 
operators <,>,<-,>-,- (or ~), & (and), and : (or) may be used. 
Except where controlled by parentheses, evaluation of expressions is left-to- 
right. In the case of certain requests, an initial + or - is stripped and inter- 
preted as an increment or decrement indicator respectively. In the presence 
of default scaling, the desired scale indicator must be attached to every 
number in an expression for which the desired and default scaling differ. 
For example, if the number register x contains 2 and the current point size 
is 10, then 

.11 {4.25i+\nxP+3)/2u 

will set the line length to 1/2 the sum of 4.25 inches + 2 picas + 3 ems. 



NOTE 



The use of white space in arithmetic expressions is not permitted. There is 
no precedence among arithmetic and logical operators, nroff/troff expres- 
sions do not recognize decimal multipliers or divisors; a high level of preci- 
sion may be achieved by mixing scales within expressions. 
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Description 



1.5. Notation 

Numerical parameters are indicated in this manual in two ways. ±N 
means that the argument may take the form N, -hN, or -N and that the 
corresponding result is to set the affected parameter to N, to increment it by 
N, or to decrement it by N respectively. Plain N means that an initial alge- 
braic sign is not an increment indicator, but merely the sign of N. Gen- 
erally, unreasonable numerical input is either ignored or truncated to a rea- 
sonable value. For example, most requests expect to set parameters to non- 
negative values: exceptions are .sp, .wh, .ch, .nr, and .if. The requests .ps, 
.ft, .po, .vs, .Is, .11, .in, and .It restore the previous parameter value in the 
absence of an argument. 

Single character arguments are indicated by single lower-case letters 
and one or two character arguments are indicated by a pair of lower-case 
letters. Character string arguments are indicated by multi-character 
mnemonics. 



2. Font and Character Size Control 



2.1. Character Set 

The Iroff character set consists of the so-called Commercial II character 
set plus a Special Mathematical Font character set. With three exceptions, 
these ASCII characters are input as themselves, and non-ASCII characters are 
input in the form \{xx where xx is a two-character name. The three ASCII 
exceptions are mapped as follows: 
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Description 



Character 



ASCII Input 



Name 



Printed by troff 
Character Name 



acute accent 
grave accent 
minus 



close quote 
open quote 
hyphen 



The characters \ and - may be input by V, \\ and \- respectively or by 
their names. (See the Table of Special Characters.) ASCII control characters 
are discussed in the section, "Input Character Translation," 

nroff understands the entire troff character set, but can in general print 
only ASCII characters, additional characters as may be available on the out- 
put device, such characters as may be able to be constructed by overstriking 
or other combination, and those that can reasonably be mapped into other 
printable characters. The exact behavior is determined by a driving table 
prepared for each device. The characters \ and _ print as themselves. 

2.2. Fonts 

Default fonts may differ from device to device. Typically, the fonts will 
include the following: Times Roman (R), Times Italic (I), Times Bold (B), 
and the Special Mathematical Font (S). The current font may be changed by 
use of the .ft request, or by embedding at any desired point either \fx, \f(xx, 
or \fN where x and xx are the name of a mounted font and N is a numerical 
font position. It is not necessary to change to the Special Font; characters 
on that font are handled automatically, 

A request for a named but not mounted font is translated into a request 
to mount the font at position 0. This position is reserved for such dynamic 
requests and is otherwise inaccessible, troff can be informed that any par- 
ticular font is mounted by use of the .fp request. The list of known fonts is 
device-dependent. In the subsequent discussion of font-related requests, F 
represents either a one or a two-character font name. The current font is 
available (as a numerical position) in the read-only number register .f . 
nroff understands font control and normally underlines italic characters. 
(See section 10,3, "Backspacing, Underlining, and Overstriking.") 
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Description 



2.3. Character Size 



The available character point sizes depend on the individual printing 
device. The .ps request is used to change or restore the point size. Alterna- 
tively, the point size can be changed between any two characters by embed- 
ding a \sN at the desired point. (N may represent the desired available size 
or \s±N may be used to increment or decrement the size by N; double-digit 
increments or decrements are expressed as \s±NN,) \sO restores the previ- 
ous size. Requested point size values that are between two legal sizes will 
yield the closer legal size. The current size is available in the .s register. 

In tro£f the escape sequence \H'N' sets the height of a character without 
affecting its width. N can be expressed in absolute values or in relative 
values of the form ±N. 



Request 
Form 
.ps ±N 



Initial 
Value 

lOpoint 



// No Notes Explanation 
Argument 



previous 



.ss N 



12/36 em 



ignored 



XSFNM off 



Point size set to ±N, Alterna- 
tively, embed \sN or \s±N. 
Any positive size value may be 
requested; if invalid, the nearest 
valid size will result, with a 
maximum size to be determined 
by the individual printing dev- 
ice. A paired sequence +N,-N 
will work because the previous 
requested value is also remem- 
bered. Ignored in nroff. 

Space-character size is set to 
JV/36ems. This size is the 
minimum word spacing in 
adjusted text. Ignored in nroff. 

Constant character space (width) 
mode is set on for font F (if 
mounted); the width of every 
character will be taken to be 
N/36 ems. If M is absent, the 



24 TECHNICAL DISCUSSION 



Description 



em is that of the character's 
point size; if M is given, the em 
is M-points. All affected charac- 
ters are centered in this space, 
including those with an actual 
width larger than this space. 
Special Font characters occurring 
while the current font is F are 
also so treated. If N is absent, 
the mode is turned off. The 
mode must be still or again in 
effect when the characters are 
physically printed. Ignored in 
nroff. 

.bd f N off - P The characters in font F will be 

artificially emboldened by print- 
ing each one three times, 
separated by N— 1 basic units. If 
N is missing the embolden 
mode is turned off. In nroff the 
default setting is .bd 3 3, speci- 
fying that characters on the font 
mounted at position 3 (normally 
bold) are to be overstruck 3 
times (i. e., printed in place a 
total of 4 times). 

The column heads above were 
printed with .bd 2 3. That is, 
the font stored at font position 2 
was emboldened by an offset of 
3, The font name itself may be 
substituted for the font position 
(e. g. .bd I 3). The — u command 
line option may be used to 
change the number of over- 
strikes using an argument that is 
functionally identical to .bd's 
second argument. (See section 
2.3, "Character Size.") The mode 
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must be still or again in effect 
when the characters are physi- 
cally printed. This request may 
affect the contents of the general 
number register .b. 

Note that it is not possible to 
turn off the emboldening in 
nroff if it is being controlled 
locally by the printing device (e. 
g„ DASI 300s). 

.bd S f A/ off - p The characters in the Special 

Font will be emboldened when- 
ever the current font is f . The 
mode must be still or again in 
effect when the characters are 
physically printed. 

.ft F Roman previous E Font changed to F. Alterna- 

tively, embed \fF. The font 
name P is reserved to mean the 
previous font. 

ApNFfile ' ignored - Font position. This is a state- 

ment that a font named F is 
mounted on position N. It is a 
fatal error if F is not known. 
Fonts and the possible range of 
their numerical positions is 
device-dependent, .fp accepts a 
third optional argument, file, 
which is an alternate version of 
the font F. 

.bd can be used to embolden characters, effectively increasing the 
number of available fonts. This capability of modifying existing fonts to 
make new ones is enhanced with the troff escape sequence, \S, used to slant 
output characters by a number of specified degrees. This escape sequence is 
stated as \S'N' where N may be any integer, negative or positive. turns 
slanting off. 
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Doscrlptlon 



3. Page control 

Top and bottom margins are not automatically provided; it is conven- 
tional to define two macros and to set traps for them at vertical positions 
(top) and -N (N from the bottom). A pseudo-page transition onto the first 
page occurs either when the first break occurs or when the first non- 
diverted text processing occurs. Arrangements for a trap to occur at the top 
of the first page must be completed before this transition. In the following, 
references to the current diversion mean that the mechanism being 
described works during both ordinary and diverted output (the former 
being considered as the top diversion level). (See section 7.4, "Diversions.") 

The physical limitations on nroff and troff output are output-device 
dependent. 

Request Initial If No Notes Explanation 
Form Value Arguntent 



.pi ±N llin llin v Page length set to ±/s/. The 

internal limitation is about 
75 inches in troff and about 
136 inches in nroff. The current 
page length is available in the .p 
register. 

.bp ±N N-l - B4,v Break page. The current page is 

ejected and a new page is 
begun. If ±JV is given, the new 
page number will be ±N, Also 
see request .ns. 

.pn ±N N-l ignored - Page number. The next page 

(when it occurs) will have the 
page number ±N, A .pn must 
occur before the initial pseudo- 
page transition to affect the page 
number of the first page. The 
current page number is in the % 
register. 
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.po ±N 0; lint previous v Page offset. The current left 

margin is set to ±N. The Iroff 
initial value provides 1 inch of 
paper margin. (See section 6, 
"Line Length and Indenting.") 
The current page offset is avail- 
able in the .o register. 

.ne N - N-l V D,y Need N vertical space. If the 

page space needed (N) is greater 
than the distance to the next 
trap (D), then a forward vertical 
space of size D occurs, which 
will spring the trap. If there are 
no remaining traps on the page, 
D is the distance to the bottom 
of the page. If the distance to 
the next trap (D) is less than one 
vertical line space (v), then 
another line could still be out- 
put before the trap is sprung. In 
a diversion, D is the distance to 
the diversion trap, if any, or is 
very large. 

.mk R none internal D Mark the current vertical place 

in an internal register (both 
associated with the current 
diversion level), or in register R, 
if given. See .rt request. 

.rl ±N none internal D,v Return upward only to a marked 

vertical place in the current 
diversion. If ±N (relative to the 
current place) is given, the place 
is ±N from the top of the page 
or diversion or, if N is absent, 
the place is that marked by a 
previous .mk. Note that the .sp 
request may be used in all cases 
instead of .rt by spacing to the 
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absolute place stored in a expli- 
cit register; e.g., using the 
sequence .mk R ... .sp \\nRu, 
(See section 5.3, "Blocks of Verti- 
cal Space.") 



4. Text Filling, Adjusting, and Centering 



4.1. Filling and Adjusting 

During fill mode, words normally are collected from input text lines 
and assembled into an output text line until some word doesn't fit. An 
attempt is then made to hyphenate the word in an effort to assemble a part 
of it into the output line. In adjust mode the spaces between the words on 
the output line are then increased to spread out the line to the current line 
length minus any current indent. A word is any string of characters delim- 
ited by the space character, the beginning or end of the input line, or by a 
combination of these. Any adjacent pair of words that must be kept 
together (neither split across output lines nor spread apart in the adjustment 
process) can be tied together by separating them with the unpaddable space 
character "X " (backslash-space). The adjusted word spacings are uniform in 
troff and the minimum interword spacing can be controlled with the .ss 
request. (See section 2, "Font and Character Size Control.") In nroff, they 
are normally nonuniform because of quantization to character-size spaces; 
however, the command-line option — e causes uniform spacing with full out- 
put device resolution. Filling, adjustment, and hyphenation can all be 
prevented or controlled. (See section 13, "Hyphenation.") The text length 
on the last line output is available in the .n register, and text base-line posi- 
tion on the page for this line is in the nl register. The text base-line high- 
water mark (lowest place) on the current page is in the .h register. 

An input text line ending with „?,!,.), ?), or !) is taken to be the end 
of a sentence, and an additional space character is automatically provided 
during filling. Multiple inter-word space characters found in the input are 
retained except for trailing spaces; initial spaces also cause a break. 

When filling is in effect, a \p may be embedded or attached to a word to 
cause a break at the end of the word and have the resulting output line 
spread out to fill the current line length. 
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A text input line that happens to begin with a control character can be 
made to not look like a control line by prefacing it with the non-printing, 
zero-width filler character \&. Still another way is to specify output transla- 
tion of a specific character into the control character using .Ir. (See section 
10.4, "Output Translation.") To suppress the break function of the control 
character ".", replace it with the single quote, 

4.2. Interrupted Text 

The copying of an input line in no-fill (i.e., no line filling) mode can be 
interrupted by terminating the partial line with a \c. The next encountered 
input text line will be considered to be a continuation of the same line of 
input text. Similarly, a word within filled text may be interrupted by ter- 
minating the word (and line) with \c; the next encountered text will be 
taken as a continuation of the interrupted word. If the intervening control 
lines cause a break, any partial line will be forced out along with any partial 
word. 

Request Initial If No Notes Explanation 
Form Value Argument 

.br - - B Break. The filling of the line 



currently being collected is 
stopped and the line is output 
without adjustment. Text lines 
beginning with space characters 
and empty text lines (blank 
lines) also cause a break. 



• .fi 



fill on 



Fill subsequent output lines. 
The register .u is 1 in fill mode 
and in no-fill mode. 



.nf 



fill on 



No-fill. Subsequent output lines 
are neither filled nor adjusted. 
Input text lines are copied 
directly to output lines without 
regard for the current line 
length. 
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.ad C adj^both adjust 



.na adjust 



.ce N off N-1 



E Line adjustment is begun. If fill 
mode is not on, adjustment will 
be deferred until fill mode is 
back on. If the type indicator c 
is present, the adjustment type is 
changed as shown in the follow- 
ing table. 



Indicator 


Adjust Type 


1 


adjust left margin only 


r 


adjust right margin only 


c 


center 


b or n 


adjust both margins 


absent 


unchanged 



The adjustment type indicator c 
may also be a number obtained 
from the .j register. (See section 
25 in the "Summary," 
"Predefined Read-Only Regis- 
ters.") 

E No-adjust. Adjustment is turned 
off; the right margin will be 
ragged. The adjustment type for 
.ad is not changed. Output line 
filling still occurs if fill mode is 
on. 

B,E Center the next N input text 
lines within the current (line- 
length minus indent). If N=0, 
any residual count is cleared. A 
break occurs after each of the N 
input lines. If the input line is 
too long, it will be left adjusted. 
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5. Vertical Spacing 



5.1. Base-line Spacing 

The vertical spacing (V) between the base-lines of successive output 
lines can be set using the .vs request with a resolution that is device- 
dependent in both nroff and troff . V must be large enough to accommo- 
date the character sizes on the affected output lines. For the common type 
sizes (9-12 points), usual typesetting practice is to set V to 2 points greater 
than the point size; troff default is 10-point type on a 12-point spacing (as 
in this document). The current V is available in the .v register. Multiple-V 
line separation (e.g., double spacing) may be requested with .Is. 

5.2. Extra Line-space 

If a word contains a vertically tall construct requiring the output line 
containing it to have extra vertical space before and/or after it, the extra- 
line-space function \x'N ' can be embedded in or attached to that word. In 
this and other functions having a pair of delimiters around their parameter 
(here '), the delimiter choice is arbitrary except that it can't look like the 
continuation of a number expression for N. If N is negative, the output line 
containing the word will be preceded by N extra vertical space; if N is posi- 
tive, the output line containing the word will be followed by N extra verti- 
cal space. If successive requests for extra space apply to the same line, the 
maximum values are used. The most recently utilized post-line extra line- 
space is available in the .a register. 

5.3. Blocks of Vertical Space 

A block of vertical space is ordinarily requested using .sp, which honors 
the no-space mode and which does not space past a trap. A contiguous 
block of vertical space may be reserved using .sv. 
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Description 



Request 
Form 

.vsN 



Initial If No Notes Explanation 
Value Argument 



l/6in;12pts previous 



AsN 



previous 



.sp N 



N-IV 



.sv N 



.OS 



E,p Set vertical base-line spacing 
size V, Transient extra vertical 
space available with \x'N ' (see 
above). 

E Line spacing set to ±N. N— 1 Vs 
(blank lines) are appended to 
each output text line. 
Appended blank lines are omit- 
ted, if the text or previous 
appended blank line reached a 
trap position. 

B,v Space vertically in either direc- 
tion. If N is negative, the 
motion is backward (upward) 
and is limited to the distance to 
the top of the page. Forward 
(dov\^nward) motion is truncated 
to the distance to the nearest 
trap. If the no-space mode is 
on, no spacing occurs (see .ns 
and .rs below). 

V Save a contiguous vertical block 
of size N. If the distance to the 
next trap is greater than N, N 
vertical space is output. No- 
space mode has no effect. If this 
distance is less than N, no verti- 
cal space is immediately output, 
but N is remembered for later 
output (see .os). Subsequent .sv 
requests will overwrite any still 
remembered N. 

Output saved vertical space. 
No-space mode has no effect. 
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Description 



r 

.ns space - D 



•rs space - D 

Blank text line - B 



Used to finally output a block of 
vertical space requested by an 
earlier .sv request. 

No-space mode turned on. 
When on, the no-space mode 
inhibits .sp requests and .bp 
requests without a next page 
number. The no-space mode is 
turned off when a line of output 
occurs, or with .rs. 

Restore spacing. The no-space 
mode is turned off. 

Causes a break and outputs a 
blank line exactly like .sp 1. 



6. Line Length and indenting 

The maximum line length for fill mode may be set with W The indent 
may be set with .in; an indent applicable to only the next output line may 
be set with .ti. The line length includes indent space but not page offset 
space. The line-length minus the indent is the basis for centering with .ce. 
The effect of .11, .in, or .ti is delayed, if a partially collected line exists, until 
after that line is output. In fill mode the length of text on an output line is 
less than or equal to the line length minus the indent. The current line 
length and indent are available in registers .1 and .i, respectively. The 
length of three-part titles produced by .tl is independently set by .It. (See 
section 14, "Three Part Titles.") 

Request Initial If No Notes Explanation 

Form Value Argument 

.11 ±N 6.5 in previous E,m Line length is set to ±N, In 

troff the maximum (line- 
length)+(page-offset) is device- 
dependent. 

.in ±N N=0 previous B,E,m Indent is set to ±N. The indent 
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^ ^ . Description 

is prepended to each output 
line. 

•ti ±N - ignored B,E,m Temporary indent. The next 

output text line will be indented 
a distance ±N with respect to 
the current indent. The result- 
ing total indent may be zero 
(equal to current page offset) but 
may not be less than the current 
page offset. The temporary 
indent applies only for the one 
output line following the 
request; the value of the current 
indent (that value stored in the 
.i register) is not changed. 



7. Macros, Strings, Diversions, and Position Traps 



7.1. Macros and Strings 

A macro is a named set of arbitrary lines that may be invoked by name 
or with a trap. A string is a named string of characters, not including a 
new-line character, that may be summoned by name at any point. Request, 
macro, and string names share the same name list. Macro and string names 
may be one or two characters long and may usurp previously defined 
request, macro, or string names. Any of these entities may be renamed with 
.rn or removed with .rm. 

Macros are created by .de and .di, and appended to by .am and .da; .di 
and .da cause normal output to be stored in a macro. Strings are created by 
.ds and appended to by .as. A macro is invoked in the same way as a 
request; a control line beginning .xx will execute the contents of macro xx 
(macro .xx may be followed by a maximum of nine argum'?nts): should the 
macro-define contain requests or escape sequences, these will be executed 
along with the rest of the defined contents of xx. If the macro is defined to 
contain text, that text will print. The strings defined as x and xx are 
inserted at any desired point with W and V(xx respectively. String refer- 
ences and macro invocations may be nested. 
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Description 



7.2. Copy Mode Input Interpretation 

During the definition and extension of strings and macros (not by diver- 
sion) the input is read in copy mode. The input is copied without interpre- 
tation except that 

■ The contents of number registers, indicated by \n, are substi- 
tuted. 

■ Strings, indicated by \*x and \*(xx, are read into the text. 

■ Arguments indicated by \$ are replaced by the appropriate 
values at the current macro level. 

■ Concealed new-lines indicated by \(new-line) are eliminated. 

■ Comments indicated by are eliminated. 

■ \t and \a are interpreted as ASCII horizontal tab and SOH respec- 
tively. (See section 9, Tabs, Leaders, and Fields.**) 

■ \\ is interpreted as \, 

■ V is interpreted as **.". 

These interpretations can be suppressed by prepending a \. For example, 
since \\ maps into a V \\n will copy as \n which will be interpreted as a 
number register indicator when the macro or string is reread. 



7.3. Arguments 

When a macro is invoked by name, the remainder of the line is taken to 
contain up to nine arguments. The argument separator is the space charac- 
ter, and arguments may be surrounded by double-quotes to permit embed- 
ded space characters. Pairs of double-quotes may be embedded in double- 
quoted arguments to represent a single double-quote. If the desired argu- 
ments won't fit on a line, a concealed new-line may be used to continue on 
the next line. 

When a macro is invoked the input level is pushed down and any argu- 
ments available at the previous level become unavailable until the macro is 
completely read and the previous level is restored. A macro's own argu- 
ments can come into play at any point within the macro with \$N, which 
introduces the Nth argument (1<N<9) into the macro's processing activity. 
If an invoked argument doesn't exist, a null string results. For example, the 
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Description 



macro xx may be defined by 

.de XX \"begin defimtion 
TYxiay is \\$1 the \\$2. 

\"endl def initian 

and called by 

,xx Monday 14th 
to produce the text 

Today is Monday the 14th. 

Notice that the \$ was concealed in the definition with a prepended \. This 
leading backslash protected the argument ($) so that it would be replaced by 
the argument of the macro when invoked, and not by the argument in 
effect when this one was being defined. The number of currently available 
arguments is in the .$ register. 

No arguments are available at the top (non-macro) level in this imple- 
mentation. Because string referencing is implemented as an input-level 
push down, no arguments are available from within a string. No arguments 
are available within a trap-invoked macro. 

Arguments are copied in copy mode onto a stack where they are avail- 
able for reference. The mechanism does not allow an argument to contain a 
direct reference to a long string (evaluated at copy time), and it is advisable 
to conceal string references (with an extra \) to delay interpretation until 
argument reference time. 



7.4. Diversions 

Processed output may be diverted into a macro for purposes such as 
footnote or sidenote processing or determining the horizontal and vertical 
size of some text for conditional changing of pages or columns. A single 
diversion trap may be set at a specified vertical position. The number regis- 
ters dn and dl respectively contain the vertical and horizontal size of the 
most recently ended diversion. Processed text that is diverted into a macro 
retains the vertical size of each of its lines when reread in no-fill mode 
regardless of the current V, Constant-spaced (.cs) or emboldened (•bd) text 
that is diverted can be reread correctly only if these modes are again or still 
in effect at reread time. One way to do this is to embed in the diversion 
the appropriate .cs or .bd requests with the transparent mechanism 
described in section 10.6, "Transparent Throughput." 
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Description 



Diversions may be nested and certain parameters and registers are asso- 
ciated with the current diversion level (the top non-diversion level may be 
thought of as the 0th diversion level). These are the diversion trap and 
associated macro, no-space mode, the internally-saved marked place (see 
.mk and .rt), the current vertical place (.d register), the current high-water 
text base-line (.h register), and the current diversion name (.z register). 



7.5. Traps 

Three types of trap mechanisms are available— page traps, a diversion 
trap, and an input-line-count trap. Macro-invocation traps may be planted 
using .wh at any page position including the top. This trap position may be 
changed using .ch. Trap positions at or below the bottom of the page have 
no effect unless or until moved to within the page or rendered effective by 
an increase in page length. 

Two traps may be planted at the same position only by first planting 
them at different positions and then moving one of the traps; the first 
planted trap will conceal the second unless and until the first one is moved. 
If the first one is moved back, it again conceals the second trap. 

The macro associated with a page trap is automatically invoked when a 
line of text is output whose vertical size reaches or sweeps past the trap 
position. Should several traps be placed so close together that a single out- 
put line could spring all of them, all but the first will be ignored. Reaching 
the bottom of a page springs the top-of-page trap, if any, provided there is a 
next page. The distance to the next trap position is available in the .t regis- 
ter; if there are no traps between the current position and the bottom of the 
page, the distance returned is the distance to the page bottom. 

A macro-invocation trap effective in the current diversion may be 
planted using .dt. The .t register works in a diversion; if there is no subse- 
quent trap a large distance is returned. 

Request Initial If No Notes Explanation 

Form Value Argument 

•de XX yy - .yy-.. _ Define or redefine the macro xx. 

The contents of the macro begin 
on the next input line. Input 
lines are copied in copy mode 
until the definition is 
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Description 

terminated by a line beginning 
with .yy, whereupon the macro 
yy is called. In the absence of 
yy, the definition is terminated 
by a line beginning with A 
macro may contain .de requests 
provided the terminating macros 
differ or the contained 
definition terminator is con- 
cealed; can be concealed as 
"\\.." which will copy as 'V." and 
be reread as 



.am XX yy 



•yy 



Append to macro (append ver- 
sion of .de). 



.ds XX string ignored 



Define a string xx containing 
string. Any initial double-quote 
in string is stripped off to permit 
initial blanks. 



.as XX string ignored 



.rm XX 



ignored 



Append string to string xx 
(append version of .ds). 

Remove request, macro, or 
string. The name xx is removed 
from the name list and any 
related storage space is freed. 
Subsequent references will have 
no effect. 



.rn XX yy 



ignored 



Rename request, macro, or string 
XX to yy. If yy exists, it is first 
removed. 



.di XX 



end 



Divert output to macro xx. Nor- 
mal text processing occurs dur- 
ing diversion except that page 
offsetting is not done. The 
diversion ends when the request 
•di or .da is encountered without 
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Description 



.da XX . end 



an argument; extraneous 
requests of this type should not 
appear when nested diversions 
are being used. 

Divert, appending to xx (append 
version of .di). 



.vihN XX ^ . V Install a trap to invoke xx at 

page position N; a negative N 
will be interpreted with respect 
to the page bottom. Any macro 
previously planted at N is 
replaced by xx, A zero N refers 
to the top of a page. In the 
absence of xx, the first found 
trap at N, if any, is removed, 

.dxxxN • . V Change the trap position for 

macro xx to be N. In the 
absence of N, the trap, if any, is 
removed. 

.dt N XX • off o.y Install a diversion trap at posi- 

tion N in the current diversion 
to invoke macro xx. Another .dt 
will redefine the diversion trap. 
If no arguments are given, the 
diversion trap is removed. 

E Set an input-line-count trap to 
invoke the macro xx after N 
lines of text input have been 
read (control or request lines 
don't count). The text may be 
in-line text or either in-line or 
trap-invoked macros represent- 
ing text. (See the discussion of 
the input-line-count .it request 
in section 7.5, "Traps.") 



.it N XX • off 
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__ ' — Description 

The macro xx will be invoked 
when all input has ended. The 
effect is the same as if the con- 
tents of XX had been at the end 
of the last file processed. 



8. Number Registers 

A variety of parameters are available to the user as predefined, named 
number registers. The user may also define his own named registers. 
Register names are one or two characters long and do not conflict with 
request, macro, or string names. Except for certain predefined read-only 
registers, a number register can be read, written, automatically incremented 
or decremented, and inserted into the input using a variety of counting 
methods. Automatically numbered sections and paragraphs are common 
usages. A number register may be used any time numerical input is 
expected or desired, (See section 1.4, "Numerical Expressions.") 

Number registers are created and modified using .nr, which specifies the 
name, numerical value, and the auto-increment size. Registers are also 
modified, if accessed with an auto-incrementing sequence. If the registers x 
and XX both contain N and have the auto-increment size M, the following 
access sequences have the effect shown: 





Effect on 


Interpreted 


Sequence 


Register 


Value 


\nx 


none 


N 


\n(xji: 


none 


N 


\n+jc 


X incremented by M 


N+M 


\n— X 


X decremented by M 


N-M 


\n+(xx 


XX incremented by M 


N+M 


\n— (xx 


XX decremented by M 





When evaluated, a number register is converted to decimal (default), 
decimal with leading zeros, lower-case roman, upper-case roman, lower-case 
alphabetic, or upper-case alphabetic according to the format specified by .af. 
The escape sequence \gxx or \g(xx gives the format used by the registers x 
or XX, This escape sequence will only return a value if the stated register 
has been set or used; otherwise, it returns 0. The value can also be saved 
and used as the second argument to .af to restore a previous format. 
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Request Initial If No Notes Explanation 
Form Value Argument 



.nr R ±N M- 



.af R c 



Arabic 



The number register R is 
assigned the value ±N with 
respect to the previous value, if 
any. The increment for auto- 
incrementing is set to M. 

Assign format c to register R. 
The available formats are 



Format 


Numbering 
Sequence 


1 


0,1,2,3,4,5,... 


001 


000,001,002,003,004,005,... 


i 


0,i,ii,iii,iv,v,... 


I 


0,I,II,III,IV,V,... 


a 


0,a,b,c,...,z,aa,ab,...,zz,aaa,.. 


A 


0,A,B,C,...,Z,AA,AB,...,ZZ, 




AAA,... 



An Arabic format having N 
digits specifies a field width of 
N digits. The read-only regis- 
ters and the width function are 
always Arabic. (See section 11.2, 
"Width Function.") 

ignored - Remove register R. If many 
registers are being created 
dynamically, it may become 
necessary to remove unneeded 
registers to recapture internal 
storage space for new registers. 
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Description 



9. Tabs, Leaders, and Fields 



9.1. Tabs and Leaders 

The ASCII horizontal tab character and the ASCII SOH (hereafter known 
as the leader character) can both be used to generate either horizontal 
motion or a string of repeated characters. The length of the generated 
entity is governed by internal tab stops specifiable with .ta. The default 
difference is that tabs generate motion and leaders generate a string of 
periods; .tc and .Ic offer the choice of repeated character or motion. There 
are three types of internal tab stops— left adjusting, right adjusting, and 
centering. In the following table D is the distance from the current position 
on the input line (where a tab or leader was found) to the next tab stop; 
next-string consists of the input characters following the tab (or leader) up 
to the next tab (or leader) or end of line; and W is the width of next-string. 



Tab 


Length of motion or 


Location of 


type 


repeated characters 


next-string 


Left 


D 


Following D 


Right 


D-W 


Right adjusted within D 


Centered 


D-W/2 


Centered on right end of D 



The length of generated motion is allowed to be negative, but that of a 
repeated character string cannot be. Repeated character strings contain an 
integer number of characters, and any residual distance is prepended as 
motion. Tabs or leaders found after the last tab stop are ignored, but may 
be used as next-string terminators. 

Tabs and leaders are not interpreted in copy mode. \t and \a always 
generate a non-interpreted tab and leader respectively, and are equivalent 
to actual tabs and leaders in copy mode but are ignored during output 
mode. 



9.2. Fields 

A field is contained between a pair of field delimiter characters, and 
consists of sub-strings separated by padding indicator characters. The field 
length is the distance on the input line from the position where the field 
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begins to the next tab stop. The difference between the total length of all 
the sub-strings and the field length is incorporated as horizontal padding 
space that is divided among the indicated padding places. The incorporated 
padding is allowed to be negative. For example, if the field delimiter is # 
and the padding indicator is U^xxx^rightU specifies a right-adjusted string 
with the string xxx centered in the remaining space. 

Request Initial If No Notes Explanation 
Form Value Argument 



.ta Nt ... 8n; O.Sin 



none 



.tC C 



Ac c 



none 



•fc ah off 



none 



off 



E.in /=R, right adjusting; t=C, 

centering; t absent, left adjust- 
ing. tR tab stops are preset every 
0.5in.; nroff every 8 nominal 
character widths. The stop 
values are separated by spaces, 
and a value preceded by + is 
treated as an increment to the 
previous stop value. 

E The tab repetition character 

becomes c, or is removed speci- 
fying motion. 

E The leader repetition character 
becomes c, or is removed speci- 
fying motion. 

The field delimiter is set to a; 
the padding indicator is set to 
the space character or to b, if 
given. In the absence of argu- 
ments the field mechanism is 
turned off. 
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Description 



10. Input and Output Conventions and Character 
Translations 

10.1. Input Character Translations 

Ways of typing in the graphic character set are discussed in section 2.1 
"Character Set." The ASCII control characters SOH and horizontal tab are 
described in section 9.1, "Tabs and Leaders." The backspace is discussed in 
section 10.3, "Backspacing, Underlining, and Overstriking." The new-line 
delimits input lines. In addition, STX, ETX, ENQ, ACK, and BEL may be used 
as delimiters or translated into a graphic with .tr. (See section 10.5, "Output 
Translation.") troff normally passes none of these characters to its output; 
nroff passes the BEL character. All others are ignored. 

The escape character \ introduces escape sequences— causes the follow- 
ing character to mean another character, or to indicate some function. A 
complete list of such sequences is given in the Summary and Index above. \ 
should not be confused with the ASCII control character ESC of the same 
name. The escape character \ can be input with the sequence \\. The 
escape character can be changed with .ec, and all that has been said about 
the default \ becomes true for the new escape character. \e can be used to 
print whatever the current escape character is. If necessary or convenient, 
the escape mechanism may be turned off with .eo, and restored with .ec. 

Request Initial If No Notes Explanation 
Form Value Ai^ument 

,ec c \ \ ' Set escape character to V or to c, 

if given. 

on - - Turn escape mechanism off. 



10.2. Ligatures 

Five ligatures are available in the current troff character set fi, fl, ff, ffi, 
and jfl. They may be input (even in nroff) by \(fi, \(fl, \(f f, \(Fi, and \(F1 
respectively. The ligature mode is normally on in troff, and automatically 
invokes ligatures during input. 
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Request Initial If No Notes Explanation 
Form Value Argument 



.Ig N off; on on - Ligature mode is turned on if N 

is absent or non-zero, and 
turned off if N=0. If N=2, only 
the two-character ligatures are 
automatically invoked. Ligature 
mode is inhibited for request, 
macro, string, register, or file 
names, and in copy mode. No 
effect in nroff . 

10.3. Backspacing, Underlining, and Overstriking 

Unless in copy mode, the ASCII backspace character is replaced by a 
backward horizontal motion having the width of the space character. 
Underlining as a form of line-drawing is discussed in section 12.4, "Line 
Drawing." A generalized overstriking function is described in section 12,1, 
"Overstriking." 

nroff automatically underlines characters in the underline font 
specifiable with .uf (normally Times Italic on font position 2.) See section 
2,2, "Fonts." In addition to .ft and \fF, the underline font is selected by .ul 
and .cu. Underlining is restricted to an output-device-dependent subset of 
reasonable characters. 

Request Initial If No Notes Explanation 

Form Value Argument 



.ul N off N-l E 
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Underline in nroff (italicize in 
troff) the next N input text 
lines. Actually, switch to under- 
line font, saving the current 
font for later restoration; other 
font changes within the span of 
a .ul will take effect, but the res- 
toration will undo the last 
change. Output generated by .tl 
is affected by the font change, 
but does not decrement N. (See 
section 14, "Three Part Titles.") 



. Description 

If N> 1, there is the risk that a 
trap-invoked macro may provide 
text lines within the span; 
environment switching can 
prevent this. 

js^ off N-i E A variant of .ul that causes 

every character to be underlined 
and causes no line breaks to 
occur in the affected input lines. 
That is, each output space fol- 
lowing .cu is like an unpaddable 
space, .cu is identical to .ul in 
troff. 

,uf F Italic Italic - Underline font set to F. In 

nroff, F may not be on position 
1 (initially Times Roman). 



10.4. Control Characters 

Both the control character and the no-break control character may 
be changed, if desired. Changes must be compatible with the design of 
macros used in the span of the change, especially trap-invoked macros. 

Request Initial If No Notes Explanation 
Form Value Argument 



xc c 
x2 c 



The basic control character is set 
to c, or reset to 

The no-break control character 
is set to c, or reset to 



10.5. Output Translation 

One character can be made a stand-in for another character using .tr. 
All text processing (e.g., character comparisons) takes place with the input 
(stand-in) character which appears to have the width of the final character. 
The graphic translation occurs at the moment of output (including diver- 
sions). 
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Description 



Request Initial If No 
Form Value Argument 

.tr abed..., none 



Notes Explanation 



Translate a into b, c into d, etc. 
If an odd number of characters 
is given, the last one will be 
mapped into the space character. 
To be consistent, a particular 
translation must stay in effect 
from input to output time. To 
reset .tr, follow request with 
previous arguments given in 
duplicate. The example given at 
the start of this entry, for 
instance, would be turned off as 
follows: •tr aacc. 



10.6. Transparent Throughput 

An input line beginning with a \! is read in copy mode and tran- 
sparently output (without the initial V); the text processor is otherwise 
unaware of the line's presence. This mechanism may be used to pass c 
trol information to a post-processor or to embed control lines in a maci 
created by a diversion. 



10.7. Comments and Concealed New-lines 

An awkwardly long input line that must stay one line (e.g., a string 
definition, or no-fiUed text) can be split into many physical lines by ending 
all but the last one with the escape \. The sequence \(new-line) is always 
Ignored— except in a comment. Comments may be embedded at the end of 
any line by prefacing them with \". The new-line at the end of a comment 
cannot be concealed. A line beginning with V will appear as a blank line 
and behave like .sp 1; a comment can be on a line by itself by beeinninc 
the line with A". / 6 6 
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Description 



11. Local Horizontal and Vertical Motions, and tlie 
Widtli Function 



11.1. Local Motions 

The functions \v'N' and \h'N' can be used for local vertical and hor- 
izontal motion respectively. The distance N may be negative; the positive 
directions are rightward and downward. A local motion is one contained 
within a line. To avoid unexpected vertical dislocations, it is necessary thi 
the net vertical local motion within a word, in filled text, and otherwise 
within a line, balance to zero. The above and certain other escape 
sequences providing local motion are summarized in the following table. 



Vertical 
Motion 


Effect in 
R nroff 


Horizontal 
Motion 


Effect in 
troff nroff 


\v'N' 


Move distance N 


\h'N' 
\(space) 

\o 


Move distance N 
Unpaddable space-size space 
Digit-size space 


\u 
\d 
\r 


em up 
em down 
1 em up 


line up 
V4 line down 
1 line up 


\l 
\^ 


1/6 em space 
1/12 em space 


ignored 
ignored 



As an example, could be generated by the sequence 

ENs-2\v'-0.4n' 2\v' 0.4n' \s+2; it should be noted in this example that the 
0.4 em vertical motions are at the smaller point size. 



11.2. Width Function 

The width function \w'string' generates the numerical width of string (i 
basic units). Size and font changes may be safely embedded in string, and 
will not affect the current environment. For example, .ti -\w'1, 'u could 
be used to temporarily indent leftward a distance equal to the size of the 
string "1. 

The width function also sets three number registers. The registers st 
and sb are set respectively to the highest and lowest extent of string relative 
to the baseline; then, for example, the total height of the string is 
\n(stu-\n(sbu. In troff the number register .ct is set to a value between 
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and 3: means that all of the characters in string were short lower case 
characters without descenders (like "e"); 1 means that at least one character 
has a descender (like "y"); 2 means that at least one character is taU (like 
"H"); and 3 means that both tall characters and characters with descenders 
are present. 



11.3. Mark Horizontal Place 

The escape sequence \kjf will cause the current horizontal position in 
the input line to be stored in register x. As an example, the construction 
\kxa;or<f\h'(\nxu+2u'a;orfif will embolden word by backing up to almost its 
beginning and overprinting it, resulting in word. 



12. Overstrike, Bracket, Line-drawing, and Zero- 
width Functions 



12.1. Overstrlking 

Automatically centered overstriking of up to nine characters is provided 
by the overstrike function Wstring'. The characters in string are overprinted 
with centers aligned; the total width is that of the widest character, string 
should not contain local vertical motion. As examples, \o'e\" produces 
eXoVmoVsl' produces i. 



12.2. Zero-width Characters 

The function \zc will output c without spacing over it, and can be used 
to produce left-aligned overstruck combinations. As examples, \z\(ci\(pl 
will produce e, and \(br\z\(rn\(ul\(br will produce the smallest possible 
constructed box Q. 



12.3. Large Brackets 

The Special Mathematical Font contains a number of bracket construc- 
tion pieces ( f U J { M I J f 1 ) that can be combined into various bracket 
styles. The function \b'string' may be used to pile up vertically the charac- 
ters in siring (the first character on top and the last at the bottom); the char- 
acters are vertically separated by 1 em and the total pile is centered l/2em 
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, Description 

above the current baseline (V4 line in nroff). For example, 

\b' \(lc\(lf 'EN I Nb' \(rc\(rf ' \x' -0,5in' \x'0.5m' produces IE . 



12.4. Line Drawing 

The function M'Nc' will draw a string of repeated c's towards the right 
for a distance N. (\1 is \(lower-case L). If c looks like a continuation of an 
expression for N, it may be insulated from N with a \&. If c is not specified, 
the - (baseline rule) is used (underline character in nroff). If N is negative, 
a backward horizontal motion of size N is made before drawing the string. 
Any space resulting from N/(size of c) having a remainder is put at the 
beginning (left end) of the string. In the case of characters that are 
designed to be connected such as baseline-rule underrule and root- 
en the remainder space is covered by overlapping. If N is less than the 
width of c, a single c is centered on a distance N. As an example, a macro 
to underscore a string can be written 
.de us 

\\$1\ 1 ' I 0\(ul' 



or one to draw a box around a string 
.de bx 

\(br\ i \\$1\ i \(br\ 1 ' i 0\(m'\ 1 ' I 0\(ul' 



such that 

,us "underlined words" 

and 

.tx "wards in a booc" 
yield underlined words and Iwords in a boTI - Notice that the text follows 
the request on the same input line and that multiple words are enclosed by 
double quotes. (Compare the mm font macros .R, .1, .B, .RI, .RB, and so 
forth.) The output cannot cross line boundaries. One way to ensure this is 
to use these macros in no-fill mode where input lines and output lines are 
identical. 



nroff/troff: TECHNICAL DISCUSSION 51 



Description 



The function \VNc' will draw a vertical line consisting of the (optional) 
character c stacked vertically apart lem (1 line in nroff), with the first two 
characters overlapped, if necessary, to form a continuous line. The default 
character is the box rule | (\(br); the other suitable character is the bold 
vertical | (\(bv). The line is begun without any initial motion relative to 
the current base line. A positive N specifies a line drawn downward and a 
negative N specifies a line drawn upward. After the line is drawn no com- 
pensating motions are made; the instantaneous baseline is at the end of the 
line. 



The horizontal and vertical line drawing functions may be used in com- 
bination to produce large boxes. The zero-width box-rule and the V4-em 
wide underrule were designed to form corners when using 1-em vertical 
spacings. For example the macro 

•de eb 

.sp -1 \" oonpensate for next autanatic base-line spacing 

\" avoid possibly cfverflowing word buffer 
Ml -.5n'\L' ! \\nau-1'\l'\\n(.lu+1n\(ul'\L - I \\nau+1\ 
'\1' ! 0u-.5n\(ul' \" drawboK 
• fi 

will draw a box around some text whose beginning vertical place was saved 
|in number reeister a (e.p.. usine .mk a) as done for this paragraph. 



In addition, troff provides drawing functions capable of drawing arcs 
and splines. 

Request Initial If No Notes Explanation 
Form Value Argument 

\D'l dh dv • . . 3 li^^ f^^^ ^j^^ current 

position by dh, diK 

\^ ^ ^ - - - Draw a circle of diameter d with 

its left side at the current posi- 
tion. 

\D'e dl dr • - . ellipse of diameters dl 

and d2 with its left side at the 
current position. 
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. Description 

\D a dhl dvl dhl dvT - - Draw a counterclockwise arc 

from the current position to 
dhl-^-dhl, dvl-^-dvl, with its 
center dhl, dvl from the 
current position, 

\D'" dhl dvl dhl dv2.,: - • Draw a B-spline from the 

current position by dhl, dvl, 
then by dhl, dvl, then ... 

The current position after using 
these drawing functions is at the 
end of the drawn line, which 
for circles and ellipses is at the 
right side. 



13. Hyphenation 

The automatic hyphenation may be switched off and on. When 
switched on with .hy, several variants may be set. A hyphenation indicator 
character may be embedded in a word to specify desired hyphenation 
points, or may be prepended to suppress hyphenation. In addition, the user 
may specify a small exception word list. 

Only words that consist of a central alphabetic string surrounded by 
(usually null) non-alphabetic strings are considered candidates for automatic 
hyphenation. Words that were input containing hyphens (minus), em- 
dashes (\(em), or hyphenation indicator characters— such as mother-in- 
law— are always subject to splitting after those characters, whether or not 
automatic hyphenation is on or off. 
Request Initial If No Notes Explanation 
Form Value Argument 

.nh no hyphen. - E Automatic hyphenation is 

turned off. 

.hy N off,N-0 on,N-l E Automatic hyphenation is 

turned on for N >1, or off for 
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•he c \% \% 



.hw WOrdl ...ignored 



N=0. If N=2, last lines (ones 
that will cause a trap) are not 
hyphenated. For N=4 and 8, 
the last and first two characters 
respectively of a word are not 
split off. These values are addi- 
tive; i.e., N=14 will invoke all 
three restrictions. 

Hyphenation indicator character 
is set to c or to the default \%. 
The indicator does not appear in 
the output. 

Specify hyphenation points in 
words with embedded minus 
signs. Versions of a word with 
terminal s are implied (that is, 
dig-it implies dig-its). This list 
is examined initially and after 
each suffix stripping. The space 
available is small— about 128 
characters. 



14. Three Part Titles 



The titling function .tl provides for automatic placement of three fields 
at the left, center, and right of a line with a title-length specifiable with At 
.tl may be used anywhere, and is independent of the normal text collecting 
process. A common use is in header and footer macros. 



Request 
Form 



Initial 
Value 



*tl 'left'ceuter'right* 



If No Notes Explanation 
Argument 



The strings left, center, and right 
are respectively left-adjusted, 
centered, and right-adjusted in 
the current title-length. Any of 
the strings may be empty, and 
overlapping is permitted. If the 
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Description 

page-number character (initially 
%) is found within any of the 
fields it is replaced by the 
current page number having the 
format assigned to register %. 
Any character may be used as 
the string delimiter. 

c % off - The page number character is 

set to c, or removed. The page- 
number register remains %. 

.It ±N 6.5 in previous E,m Length of title set to ±N. The 

line-length and the title-length 
are independent. Indents do 
not apply to titles; page-offsets 
do. 
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15. Output Line Numbering 



Automatic sequence numbering of output lines may be requested 
with .nm. When in effect, a three-digit, arabic number plus a digit- 

3 space is prepended to output text lines. The text lines are thus offset by 
four digit-spaces, and otherwise retain their line length. A reduction in 
line length may be desired to keep the right margin aligned with an 

6 earlier margin. Blank lines, other vertical spaces, and lines generated 
by .tl are not numbered. Numbering can be temporarily suspended 
with .nn, or with an .nm followed by a later .nm +0. In addition, a 

9 line number indent /, and the number-text separation S may be 
specified in digit-spaces. Further, it can be specified that only those 
line numbers that are multiples of some number M are to be printed 
12 (the others will appear as blank number fields). 

Request Initial If No Notes Explanation 
Form Value Argument 



.nm ±N MSI off 



•nn N - N-i E 



Line number mode. If ±N is 
given, line numbering is turned 
on, and the next output line 
numbered is numbered ±N. 
Default values are M= 1, S= 1, 
and /=0. Parameters 
corresponding to missing argu- 
ments are unaffected; a non- 
numeric argument is considered 
missing. In the absence of all 
arguments, numbering is turned 
off; the next line number is 
preserved for possible further 
use in number register In. 

The next N text output lines are 
not numbered. 
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As an example, the paragraph portions of this section are numbered 
with M=3: .nm 1 3 was placed at the beginning; .nm was placed at the 

15 end of the first paragraph; and .nm +0 was placed in front of this para- 
graph; and .nm finally placed at the end. Line lengths were also 
changed (by \w'0000 u) to keep the right side aligned. Another exam- 

18 pie is .nm +55x3 which turns on numbering with the line number of 
the next line to be 5 greater than the last numbered line, with M-5, 
with spacing S untouched, and with the indent / set to 3. 



16. Conditional Acceptance of Input 



In the following, c is a one-character, built-in condition name, ! signifies 
not, N is a numerical expression, string! and string! are strings delimited by 
any non-blank, non-numeric character not in the strings, and anything 
represents what is conditionally accepted. 
Request Initial If No Notes Explanation 
Form Value Argument 



.if c anything 

.if !c anything 

.if N anything 

.if !N anything 

.if 'string!' string!' anything 

.if V string!' string!' anything 

.ie c anything 

.el anything - 



If condition c true, accept any- 
thing as input; in multi-line case 
use Wanything"^. 

If condition c false, accept any- 
thing. 

If expression N > 0, accept any- 
thing. 

If expression N < 0, accept any- 
thing. 

If string! identical to string!, 
accept anything. 

If string! not identical to string!, 
accept anything. 

If portion of if-else; all above 
forms (like .if). 

Else portion of if-else. 
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The built-in condition names are 



Condition 
Name 



True If 



n 



o 



e 



t 



Current page number is odd 
Current page number is even 
Formatter is troff 
Formatter is nroff 



If the condition c is true, or if the number N is greater than zero, or if the 
strings compare identically (including motions and character size and font), 
anything is accepted as input. If a ! precedes the condition, number, or 
string comparison, the sense of the acceptance is reversed. 

Any spaces between the condition and the beginning of anything are 
skipped over. The anything can be either a single input line (text, macro, or 
whatever) or a number of input lines. In the multi-line case, the first line 
must begin with a left delimiter \{ and the last line must end with a right 
delimiter \J. The left delimiter must be followed by either a command or 



.if 58>1 \{ 'sp 0,5i 

Following this delimiter with a backslash (\{\), escaping the newline, yields 
an equivalent arrangement. 

The request .ie (if-else) is identical to .if except that the acceptance state 
is remembered. A subsequent and matching .el (else) request then uses the 
reverse sense of that state, .ie - .el pairs may be nested. 

Some examples are 

.if e .tl ' Even Page 

which outputs a title if the page number is even; and 

.ie \ii%>1 \{\ 
'sp 0,5i 
.U ' Page %" ' 
'sp I 1.2i \} 
.el .sp I 2.5i 

which treats page 1 differently from other pages. 



text: 
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Description 



17. Environment Switching 

A number of the parameters that control the text processing are gath- 
ered together into an environment, which can be switched by the user. The 
environment parameters are those associated with requests noting E in their 
Notes column; in addition, partially collected lines and words are in the 
environment. Everything else is global; examples are page-oriented parame- 
ters, diversion-oriented parameters, number registers, and macro and string 
definitions. All environments are initialized with default parameter values. 

Request Initial If No Notes Explanation 
Form Value Argument 

•ev N N-O previous - Environment switched to 

environment 0<N<2. Switch- 
ing is done in push-down 
fashion so that restoring a previ- 
ous environment must be done 
with .ev rather than specific 
reference. 
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18. Insertions from the Standard Input 

The input can be temporarily switched to the system standard input 
with .rd, which will switch back when two new-lines in a row are found 
(the extra blank line is not used). This mechanism is intended for inser- 
tions in form-letter-like documentation. On the UNIX system, the standard 
input can be the user's keyboard, a pipe, or a file. 

Request Initial If No Notes Explanation 
Form Value Argun^ent 

.rd prompt - prompMEL - Read insertion from the stan- 

dard input until two new-lines 
in a row are found. If the stan- 
dard input is the user's key- 
board, prompt (or a BEL) is writ- 
ten onto the user's terminal, .rd 
behaves like a macro, and argu- 
ments may be placed after 
prompt. 

.ex - - - Exit from nroff/troff. Text pro- 

cessing is terminated exactly as 
if all input had ended. 

If insertions are to be taken from the terminal keyboard while output is 
being printed on the terminal, the command-line option -q will turn off 
the echoing of keyboard input and prompt only with BEL. The regular 
input and insertion input cannot simultaneously come from the standard 
input. 

As an example, multiple copies of a form letter may be prepared by 
entering the insertions for all the copies in one file to be used as the stan- 
dard input, and causing the file containing the letter to reinvoke itself using 
.nx; the process would ultimately be ended by an .ex in the insertion file. 
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Description 



19. Input/Output File Switching 

Request Initial If No Notes Explanation 
Form Value Argument 

•so file - ' - Switch source file. The top 

input (file reading) level is 
switched to file. When the new 
file ends, input is again taken 
from the original file; .so's may 
be nested. Note that file should 
be preprocessed, if necessary, 
before being called by .so. eqn, 
tbl, pic, and grap will not reach 
through .SOS to process an object 
file. Once a .so is encountered, 
the processing of file is immedi- 
ate. Processing of the original 
file (e, g., a macro that is still 
active) is suspended. 

.nx file end-of-file - - Next file is file. The current file 

is considered ended, and the 
input is immediately switched to 
file. 

Copy the contents of file, unin- 
terpreted into troff output file at 
this point. Havoc ensues unless 
the motions in the file restore 
the current horizontal and verti- 
cal position. 

Corrects troff's idea of the 
current line number, N, and the 
current file, file, for use in error 
messages. 

Pipe output to program. This 



.cf file 



.If N file 



.pi program - 
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request must occur before any 
printing occurs. No arguments 
are transmitted to program. 



20. Miscellaneous 



Request Initial If No 
Form Value Argument 

.mc c N ' off 



Notes Explanation 



'.,m Specifies that a margin character 
c appear a distance JV to the 
right of the right margin after 
each non-empty text line (except 
those produced by .tl). If the 
output line is too long (as can 
happen in no-fill mode) the 
character will be appended to 
the line. If N is not given, the 
previous N is used; the initial N 
is 0.2 inches in nroff and 1 em 
in troff . The margin character 
used with this paragraph was a 
12-point box-rule. 



.tm string - new-line - After skipping initial blanks, 

string (rest of the line) is read in 
copy mode and written on the 
user's terminal. 



.ig t/y - .yy-« - Ignore input lines, .ig behaves 

exactly like .de except that the 
input is discarded. (See section 
7, "Macros, Strings, Diversions, 
and Position Traps.") The input 
is read in copy mode, and any 
auto-incremented registers will 
be affected. 
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.pm t - all - Print macros. The names and 

sizes of all of the defined macros 
and strings are printed on the 
user's terminal; if t is given, 
only the total of the sizes is 
printed. The size is given in 
blocks of 128 characters. 

.fl - - B Flush output buffer. 

•ab text - Abort - Prints text on the diagnostic out- 

put (normally the terminal) and 
terminates without further pro- 
cessing. If text is missing, the 
message "User Abort" is printed. 
The output buffer is flushed. 
Used in interactive debugging to 
force output. 

,sy cmd args - - - cmd is executed but its output is 

not captured at this point. The 
standard input for cmd is closed. 
Output for processing must be 
explicitly saved in an output 
file. 
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21. Output and Error Messages 

The output from .tm, .pm, and the prompt from .rd, as well as various 
error messages are written onto the UNIX system's standard error message 
output. The latter is different from the standard output, where nroff for- 
matted output goes. By default, both are written onto the user's terminal, 
but they can be independently redirected. 

Various error conditions may occur during the operation of nroff and 
trof f . Certain less serious errors having only local impact do not cause pro- 
cessing to terminate. Two examples are "word overflow," caused by a word 
that is too large to fit into the word buffer (in fill mode), and "line over- 
flow," caused by an output line that grew too large to fit in the line buffer; 
in both cases, a message is printed, the offending excess is discarded, and 
the affected word or line is marked at the point of truncation with a • in 
nroff and a in troff. The philosophy is to continue processing, if possi- 
ble, on the grounds that output useful for debugging may be produced. If a 
serious error occurs, processing terminates, and an appropriate message is 
printed. Examples are the inability to create, read, or write files, and the 
exceeding of certain internal limits that make future output unlikely to be 
useful. 
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Special Characters 



1. Input Names for \ and - and for Non-ASCII 
Special Characters 





Input 


Character 




Input 


Character 


Char 


Name 


Name 


Char 


Name 


Name 


n 




close quote 


fi 


\(fi 


fi ligature 


n 




open quote 


ff 


\(ff 


ff ligature 


t 


\(fm 


foot mark 


ff 


\(fl 


fl ligature 


c 


\(ct 


cent sign 


ffi 


\(Fi 


ffi ligature 




\(em 


3/4 em dash 


ffl 


\(F1 


ffl ligature 




V 


current font minus 


V* 


\(14 


one-fourth 




\(ru 


rule 


V4 


\(12 


one half 




\(hy 


hyphen 


% 


\(34 


three-fourths 






literal hyphen 


t 


\(dg 


dagger 


o 


\(de 


degree 


t 


\(dd 


double dagger 


• 


\(bu 


bullet 


® 


\(rg 


registered 


□ 


\(sq 


square 




\(co 


copyright 


■ 


\(bx 


box 




\(tm 


trademark 
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2. Non-ASCII Characters and Mntis on the Standard 
Fonts 

The upper-case Greek letter names followed by f are mapped into 
upper-case English letters in whatever font is mounted on font position one 
(default Times Roman). The special math plus, minus, and equals are pro- 
vided to insulate the appearance of equations from the choice of standard 
fonts. 





Input 


Character 




Input 


Character 


Char 


Name 


N 


Char 


Name 


Name 


A 


\(*A 


Alphaf 


ot 




alpha 


B 




Betaf 


3 




beta 


r 


\(*G 


Gamma 


J 






A 




Delta 




\(*d 




E 






€ 






Z 


\(*z 


Zetaf 


t 

i 


\(*z 


zeta 


H 


\(*Y 


Etat 






eta 


e 


\CH 


Theta 


e 


\Ch 


theta 


I 


\(*I 


lotaf 


t 




iota 


K 


\(*K 


Kappaf 


K 


\(*k 


kappa 


A 


\(*L 


Lambda 


X 


\(*1 


lambda 


M 


\(*M 


Mut 


M 


\Cm 


mu 


N 


\(*N 


Nut 




\(*n 


nu 


M 


\(*c 


Xi 




\(*c 


xi 





\(*o 


Omicront 





\(*o 


omicron 


n 


\(*P 


Pi 


TT 


\(*P 


pi 


p 


\(*R 


Rhot 


P 


\(*r 


rho 


2 


\(*s 


Sigma 


a 


\(*s 


Sigma 


T 


\(*T 


Taut 


9 


\(ts 


terminal sigma 


Y 


\(*u 


Upsilon 


T 


\Ct 


tau 




\(*F 


Phi 


V 


\(*u 


upsilon 


X 


\(*x 


Chit 


4> 


\(*f 


phi 




\(*Q 


Psi 


X 


\(»x 


chi 


n 


\(*w 


Omega 




\(*q 


psi 








(a) 


\(*w 


omega 
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Input 


Character 




Char 


Name 


Name 


Gift's •* 


+ 


\(pl 


math plus 


oo 




\(mi 


math minus 




-1 


\(eq 


math equals 


V 


• 


\r* 


math star 






\(aa 


acute accent 


oc 




\(ga 


grave accent 







\(ul 


underrule 


€ 


7 


\(sl 


slash 

(matching backslash) 


1 
1 




\(sr 


square root 






\(rn 


root en extender 




> 


\(>- 


>- 


o 


< 


\(<- 


<- 


f 




\(~ 


identically equal 


I 


sat 


xo- 


approx 





\(ap 


approximates 


1 




\(!- 


not equal 


J 


-» 


\(-> 


right arrow 


\ 


4- 


\(<- 


left arrow 


\ 


t 


\(ua 


up arrow 


1 


\(da 


down arrow 




X 


\(mu 


multiply 


1 

I 




\(di 


divide 


± 


\(+- 


plus-minus 


J 


U 


\(cu 


cup (union) 


n 


\(ca 


cap (intersection) 


\ 


c 


\(sb 


subset of 


1 




\(sp 


superset of 




Q 


\(ib 


improper subset 


n 


2 


\(ip 


improper superset 


§ 



Input 




Name 


Name 


\(if 


infinity 


\(pd 


partial derivative 


\(gr 


gradient 


\(no 


not 


\(pt 


proportional to 


\(es 


empty set 


\(mo 


member of 


\(or 


or 


\(br 


box vertical rule 


\(rh 


right hand 


\(lh 


left hand 


\(ci 


circle 


\(lt 


left top of big curly 




bracket 


\(lb 


left bottom 


\(rt 


right top 


\(rb 


right bottom 


\(lk 


left center of big 




curly bracket 


\(rk 


right center of big 




curly bracket 


\(bv 


bold vertical 


\(lf 


left floor (left bottom 




of big square bracket) 


\(rf 


right floor (right bottom) 


\(lc 


left ceiling (left top) 


\(rc 


right ceiling (right top) 


\cs 


control-shift indicator 


\vs 


visible space indicator 


\(sc 


section 
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CHECKMM(l) 



NAME 

checkmm — checks documents formatted with the mm macros 

SYNOPSIS 

checkmm [ file(s) ] 

DESCRIPTION 

checkmm stands for "check memorandum macros." Use checkmm to check 
for syntax errors in files that have been prepared for the mm(l) or mml{l) 
command. For example, checkmm checks that you have a .DE (display end 
macro) corresponding to every .DS (display start macro). 

The output for checkmm is the number of lines checked, and a list of macros 
that are unfinished because of missing macros. If you do not include a file 
name on the command line, checkmm takes input from standard input. 

SEE ALSO 

eqn(l), mm(l), mmt(l), mvt(l), neqn(l), tbl(l), and mm(5). 
DIAGNOSTICS 

"checkmm Cannot open file($) " if file($) is unreadable. The remaining output 
of the program is diagnostic of the source file. 
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COL(l) 



COL(l) 



NAME 

col — filter reverse line-feeds 

SYNOPSIS 

col [ -bfpx 1 [ - 1 

DESCRIPTION 

col reads from the standard input and writes onto the standard output. It per- 
forms the line overlays implied by reverse line feeds (ASCII code ESC-7), and 
by forward and reverse half-line-feeds (ESC-9 and ESC-8). col is particularly 
useful for filtering multicolumn output made with the .rt command of nroff 
and output resulting from use of the tbl(l) preprocessor. 
If the — b option is given, col assumes that the output device in use is not 
capable of backspacing. In this case, if two or more characters are to appear in 
the same place, only the last one read will be output. 

Although col accepts half-line motions in its input, it normally does not emit 
them on output. Instead, text that would appear between lines is moved to 
the next lower full-line boundary. This treatment can be suppressed by the 
-£ (fine) option; in this case, the output from col may contain forward half- 
line-feeds (ESC-9), but will still never contain either kind of reverse line 
motion. 

Unless the — x option is given, col will convert white space to tabs on output 
wherever possible to shorten printing time. 

The ASCII control characters SO (\017) and SI (\016) are assumed by col to start 
and end text in an alternate character set. The character set to which each 
input character belongs is remembered, and on output SI and SO characters are 
generated as appropriate to ensure that each character is printed in the correct 
character set. 

On input, the only control characters accepted are space, backspace, tab, 
return, new-line, SI, SO, VT (\013), and ESC followed by 7, 8, or 9. The VT 
character is an alternate form of full reverse line-feed, included for compati- 
bility with some earlier programs of this type. All other non-printing charac- 
ters are ignored. 

Normally, col will ignore any escape sequences unknown to it that are found 
in its input; the — p option may be used to cause col to output these sequences 
as regular characters, subject to overprinting from reverse line motions. The 
use of this option is highly discouraged unless the user is fully aware of the 
textual position of the escape sequences. 

SEE ALSO 

mm(l), nro£f(l), tbl(l). 
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NOTES 

The input format accepted by col matches the output produced by nrotf with 
either the -T37 or -Tip options. Use -T37 (and the -f option of col) if the 
ultimate disposition of the output of col will be a device that can interpret 
half-line motions, and -Tip otherwise. 

BUGS 

Cannot back up more than 128 lines. 

Allows at most 800 characters, including backspaces, on a line. 
Local vertical motions that would result in backing up over the first line of 
the document are ignored. As a result, the first line must not have any super- 
scripts. 
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NAME 

daps - postprocessor for the Autologic APS-5 phototypesetter 

SYNOPSIS 

daps [ option(s) ][ — ] [ file(s) ] 

DESCRIPTION 

daps prints file(s) created by troff(l) on an Autologic APS-5 phototypesetter. 
If you do not specify a fil€(sh the standard input is printed, daps understands 
the following options: 

-b reports whether the typesetter is busy; does not print output 
— h string 

prints string in this job's header. The header appears on a page 
preceding the output, 
-o list prints pages whose numbers are given in a list, containing single 
numbers or ranges N -N2. A missing means the lowest- 
numbered page, a missing means the highest, 
reports the number of 11-inch pages generated by this job. Use this 
option only after you have checked with the typesetter operations 
staff. 

-s n stops after every n pages of output, daps continues when you push 

the PROCEED button on the typesetter, 
-t directs output to the standard output instead of the typesetter, 
-w waits for typesetter to become free, then prints output. 
The file(s) that you submit to daps should be prepared under the -Taps 
option of trDff(l). 



— r 



FILES 



/dev/aps APS-5 phototypesetter device 

/usr/lib/font/devaps/* font description files for APS-5 



SEE ALSO 

dilO(l), tc(l), troffClX troff(5), mmt(l), mvt(l). 

BUGS 

Installations with an Autologic APS-5 phototypesetter should be aware that 
getting a good match to their Autologic fonts will almost certainly require 
hand-tuning of the font description files (see FILES above). 
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NAME 

dilO - postprocessor for the Imagen Imprint-10 laser printer 

SYNOPSIS 

dilO [ option(s) 1 [ — 1 [ fUe(s) ] 

DESCRIPTION 

dilO prints file(s) created by tro£f(l) on an Imagen Imprint-10 laser printer. It 
is a phototypesetter simulator that can handle troff output prepared for any 
supported typesetter. However, files sent to dilO look best when prepared 
with the -TilO option of troff , 

If you do not specify a file, the standard input is printed. dilO understands 
the following options: 

-o list prints pages whose numbers are given in a list containing single 
numbers N, or ranges ^."^2' ^ '"issi'^g means the lowest- 
numbered page, a missing means the highest. 

— t directs output to the standard output instead of the typesetter. 

-r n resolution of printer is n dots per inch. dilO will adjust its choice of 
raster files to produce properly scaled output. The default is 240. 

HLES 

/usr/lib/font/devilO/* font description files for Imagen Impnnt-10 

/usr/lib/font/devilO/rastilO/* raster files for Imprint-10 
/tmp/dimp* output of dilO ready for Imagen 

SEE ALSO 

dap8(l), tc(l), trotf(l), tro£f(5), mmt(l), mvt(l). 
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NAME 

diffmk - mark differences between files 

SYNOPSIS 

diffmk [ — ] file! file! file3 

DESCRIPTION 

diffmk compares two versions of a file and creates a third file that includes 
"change mark" requests (.mc) for nroff or troff(l). filel and file! are the old 
and new versions of the file, diffmk generates /i/e3, which contains the lines 
of filel plus inserted formatter "change mark" requests. When fileS is format- 
ted, changed or inserted text is shown by | at the right margin of each line. 
The position of deleted text is shown by a single asterisk: 
If anyone is so inclined, diffmk can be used to produce listings of C (or 
other) programs with changes marked. A typical command line for such use 
is 

diffmk old,c new.c Imp; nroff macs tmp | pr 
where the file macs contains 



.nf 
.eo 
.ec 

The .11 request might specify a different line length, depending on the nature 
of the program being printed. The .eo and .nc requests are probably needed 
only for C programs. 

SEE ALSO 

nroff(l), and troff(l). 

Where diffmk encounters - it uses the standard input. 

BUGS ^ 

Aesthetic considerations may dictate manual adjustment of some output. File 
differences involving only formatting requests may produce undesirable out- 
put, i.e., replacing .sp by .sp 2 will produce a "change mark" on the preceding 
or following line of output. 
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NAME 

eqn - format mathematical text for troff 
SYNOPSIS 

eqn [-d xx] [-p n] [-s n] [-£ n] [-Tttyjype] [ — ] [file(s)] 
DESCRIPTION 

eqn is a troff (1) preprocessor for typesetting mathematical text on a photo- 
typesetter. Normal usage is: 

eqn [option(s)] file(s) \ troff [option(s)] \ [typesetter] 
If you do not specify files (or if you specify - as the last argument), eqn reads 
the standard input, eqn prepares output for the typesetter that you name in 
the -T option. Currently supported devices are -Taps (Autologic APS-5), 
and -TilO (Imagen Imprint-10), The default is -Taps. 

A line beginning with .EQ marks the start of an equation; the end of an equa- 
tion is marked by a line beginning with .EN. troff does not alter these lines, 
so they may be defined in macro packages to get centering, numbering, etc. 
You may also name two characters as delimiters; eqn treats subsequent text 
between delimiters as input. You may set delimiters to characters x and x 
with the command line argument -d xx or (more commonly) with delim xx 
between .EQ and .EN. The left and right delimiters may be the same character; 
the dollar sign is often used as such a delimiter. Turn delimiters off with 
delim off. eqn touches only text that is between delimiters or between .EQ 
and .EN. 

Set apart keywords recognized by eqn with spaces, tabs, new-lines, braces, 
double quotes, tildes, and circumflexes. Use braces, {), for grouping; generally 
speaking, anywhere you can use a single character such as x, you may use a 
complicated construction enclosed in braces instead. Tilde (-) represents a 
full space in the output, circumflex C") half as much. 

Subscripts and superscripts are produced with the keywords sub and sup. 
Fractions are made with over, sqrt makes square roots. 

The keywords from and to introduce lower and upper limits. Left and right 
brackets, braces, etc., of the right height are made with left and right. Legal 
characters after left and right are braces, brackets, bars, c and f for ceiling and 
floor, and for nothing at all (useful for a right-side-only bracket). A left 
thing need not have a matching right thing, but a right thing must have a 
matching left thing. 

Vertical piles of things are made with pile, Ipile, cpile, and rpile. Piles may 
have arbitrary numbers of elements; Ipile left-justifies, pile and cpile center 
(but with different vertical spacing), and rpile right justifies. Matrices are 
made with matrix. In addition, there is rcol for a right-justified column. 
Diacritical marks are made with dot, dotdot, hat, tilde, bar, vec, dyad, and 
under. 

You may change point sizes and fonts with size n or size ±n, roman, italic, 
bold, and font n. You may change point sizes and fonts globally in a docu- 
ment by gsize n and gfont n, or by the command-line arguments -sn and 
-in. 
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Normally, subscripts and superscripts are reduced by 3 points from the previ- 
ous size; you may change this with the command-line argument -pn. 
You can line up successive display arguments. Place mark before the desired 
hneup point in the Erst equaHon; place lineup at the place that is to line up 
vertically in subsequent equations. 

You may define shorthands or redefine existing keywords with define: 
define thing % replacement % 

defines a new token called thing that is replaced by replacement whenever it 
appears thereafter. The % may be any character that does not occur in revlace- 
ment, ^ 

Keywords such as sum, int, inf, and shorthands such as >«, and -> are 
recognized. Greek letters are spelled out in the desired case, as in alpha or 
GAMMA. Mathematical words such as sin, cos, and log are made Roman 
automatically. Irotf(l) four-character escapes such as \(dd, which produces the 
double dagger, may be used anywhere. Strings enclosed in double quotes 
(...) are passed through untouched; this permits keywords to be entered as 
text, and can be used to communicate with troff(l) when all else fails Full 
details are given in the REFERENCE cited below. 
SEE ALSO 

mmt(l), mvt(l), neqn(l), nroff(l), tbl(l), troff(l), eqnchar(5), mm(5), and 
niv(5). 

The Preprocessor eqn" in the User's Guide, 



BUGS 



^^n.^^^tf^^ P^'^'^^l^eses, etc, it is necessary to quote them, as in bold 

12.3 . When you use eqn with the mm macro package, displayed equations 
must appear only inside displays. 
See also BUGS under troff(l). 
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NAME 

eqnchar - special character definitions for eqn and neqn 
SYNOPSIS 

eqn /usr/pub/eqnchar [ option(s) ] [ ~ 1 [ file(s) ] \ troff ( oplion(s) ] 
eqn /usr/pub/cateqnchar [ oplion(s) ] [ ~ 1 [ file(s) ] | tro£f [ option(s) ] 
neqn /usr/pub/eqnchar [ option(s) J [ ~ ] [ file(s) ] | nrotf [ option(s) ] 
eqn -Taps /usr/pub/apseqnchar [ option(s) J [ — ] [ file(s) ] \ 
troff [ option(s) ] 
DESCRIPTION 

/usr/pub/eqnchar contains the following troff(l) and nroff(l) character 
definitions that are not ordinarily available on a phototypesetter or printer. 
These definitions are primarily intended for use with eqn(l) and neqn(l). 
eqnchar contains definitions for the following characters: 



ciplus 


e 


II 


II 


square 


□ 


citimes 




tangle 


( 


circle 


O 


wig 




rangle 


) 


blot 


■ 


-wig 




hbar 


fi 


bullet 


• 


>wig 


> 


ppd 


± 


prop 


oc 


<wig 


< 


<-> 




empty 





'^wig 




<-> 


<*> 


member 


€ 


star 


• 


l< 


< 


nomem 


i 


bigstar 




l> 


> 


cup 


u 


^dot 




ang 




cap 


n 


orsign 


V 


rang 


L 


incl 


c 


andsign 


A 


3dot 




subset 


c 


^del 




thf 




supset 




oppA 


V 


quarter 




hubset 


Q 


oppE 


3 


Squarter 




Isupset 




angstrom 


A 


degree 





scrL 


e 


— < 


< 


— > 


> 







/usr/pub/apseqnchar is a version of eqnchar tailored for the Autologic APS-5 
phototypesetter. If you use apseqnchar, output will not look optimal on other 
phototypesetters. cateqnchar is more -device-independent and should pro- 
duce output that looks reasonable on any device supported by troff(l). You 
may link /usr/pub/eqnchar to /usr/pub/cateqnchar or to 
/usr/pub/apseqnchar. By default, /usr/pub/eqnchar is linked to 
/usr/pub/apseqnchar. 
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SEE ALSO 

eqn(l), neqn(l), nro£f(l), tro£f(l), min(l), inmt(l), and invt(l). 
The Preprocessor eqn" in the User's Guide, 

FILES 

/usr/pub/eqnchar 

/usr/pub/apseqnchar 

/usr/pub/cateqnchar 
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NAME 

font - description files for troff 

SYNOPSIS 

troff -Tttyjype ... 

DESCRIPTION 

For each phototypesetter that troff(l) supports and that is available on your 
system, there is a directory that contains files describing the phototypesetter 
and its fonts. This directory is named /usr/lib/font/devUyJype, where 
ttyjype is the name of the phototypesetter. Currently, the supported devices 
are aps for the Autologic APS-5 and ilO for the Imagen Imprint-10 laser 
printer. 

For a particular phototypesetter, ttyjype, the ASCII file DESC in the directory 
devttyjype within the troff source directory describes its characteristics, A 
binary version of this file (described below) is found in 
/u9r/lib/font/dev«y typelDESCout. Each line of this ASCII file starts with a 
word that identifies" the characteristic, which is followed by appropriate 
specifiers. Blank lines and lines beginning with the # character are ignored. 

The legal lines for DESC are: 

res num resolution of device in basic increments per inch 

hor num smallest unit of horizontal motion 

vert num smallest unit of vertical motion 

unitwidth num pointsize in which widths are specified 
sizescale num scaling for fractional pointsizes 

paperwidth num width of paper in basic increments 
paperlength num length of paper in basic increments 
biggestfont num maximum size of a font 

sizes num nwm ... list of pointsizes available on typesetter, ter- 
minated by 

fonts num name ... number of initial fonts followed by the names of 
the fonts. For example: 
fonts 4 R I B S 

charset this always comes last in the file and is on a line 

by itself. Following it is the list of special char- 
acter names for this device. Names are separated 
by a space or a newline. The list can be as long 
as necessary. Names not in this list are not 
allowed in the font description files. 

res is the basic resolution of the device in increments per inch, hor and vert 
describe the relationships between motions in the horizontal and vertical 
directions. If the device is capable of moving in single basic increments in 
both directions, both hor and vert would have values of 1. If the vertical 
motions only take place in multiples of two basic units while the horizontal 
motions take place in the basic increments, then hor would be 1, while vert 
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name name 
internalname name 
special 

ligatures name ... 

spacewidth num 
charset 



would be 2. unilwidth is the pointsize in which all width tables in the font 
description files are given, troff automatically scales the widths from the 
unitwidth size to the pointsize it is working with, sizescale is not currently 
used and is 1. paperwidth is the width of the paper in basic increments. The 
APS-5 is 6120 increments wide, paperlength is the length of a sheet of paper 
in the basic increments, biggestfont is the maximum number of characters on 
a font. 

For each font supported by the phototypesetter, there is also an ASCII file 
with the same name as the font (e.g., R, I, CW). The format for a font 
description file is: 

name of the font, such as R or CW 

internal name of font 

sets flag indicating that the font is special 

Sets flag indicating font has ligatures. The list of 
ligatures follows and is terminated by a zero. 
Accepted ligatures are: ff ft £1 fii ffl. 

specifies width of space if something other than 
default (1/3 of an em) is desired. 

The character set must come at the end. Each 
line following the word charset describes one 
character in the font. Each line has one of two 
formats: 

name width kerning code 
name " 

where name is either a single ASCII character or 
a special character name from the list found in 
DESC. The width is in basic increments. The 
kerning information is 1 if the character des- 
cends below the line, 2 if it rises above the letter 
y, and 3 if it both rises and descends. The kern- 
ing information for special characters is not used 
and so may be 0. The code is the number sent to 
the typesetter to produce the character. The 
second format is used to show that the character 
has more than one name. The double quote 
shows that this name has the same values as the 
preceding line. The kerning and code fields are 
not used if the width field is a double quote 
character. The total number of different charac- 
ters in this list should not be greater than the 
value of biggestfont in the DESC file (see above). 
In the source version of DOCUMENTER'S WORKBENCH Software, troff and its 
postprocessors read this information from binary files produced from the 
ASCII files by makedev, a program distributed with troff source. For those 
having a source license and need to know, a description of the format of these 
files follows: 
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The file DESC.out starts with the dev structure, defined by dev.h: 
/* 

dev.h: characteristics of a typesetter 
♦ / 



struct dev { 

unsigned short filesize; /♦ number of bytes in file, 

/♦ excluding dev part ♦/ 



♦ / 



basic resolution in goobies/inch ♦/ 
goobies horizontally ♦/ 

size at which widths are given*/ 
number fonts physically available ♦/ 
number of pointsizes */ 
scaling for fractional pointsizes ♦/ 
max line length in units ♦/ 
max paper length in units ♦/ 
number of funny names in chtab ♦/ 
length of chname table */ 
max # of chars in a font ♦/ 
in case of expansion ♦/ 



short res; /♦ 
short hor; /♦ 
short vert; 

short unitwidth; /♦ 
short nfonts; /* 
short nsizes; /♦ 
short sizescale; /♦ 
short paperwidth; /♦ 
short paperlength; /♦ 
short nchtab; /♦ 
short Ichname; /♦ 
short biggestfont; /• 
short spare; /♦ 
); 

filesize is just the size of everything in DESC.out excluding the dev structure. 
nfonts is the number of different font positions available, nsizes is the number 
of different pointsizes supported by this typesetter, nchtab is the number of 
special character names. Ichname is the total number of characters, including 
nulls, needed to list all the special character names. At the end of the struc- 
ture is one spare for later expansions. 

Immediately following the dev structure are a number of tables. First is the 
sizes table, which contains nsizes + 1 shorts(a null at the end), describing the 
pointsizes of text available on this device. The second table is the 
funny jharjndexjable , It contains indices into the table that follows it, the 
funny jharjtrings. The indices point to the beginning of each special charac- 
ter name that is stored in the funny jharjtrings table. The funny jharjtrings 
table is Ichname characters long, while the funny _charjndexjable is nchtab 
shorts long. 

Following the dev structure will occur nfonts [font]. out files, which are used to 
initialize the font positions. These [font). out files, which also exist as separate 
files, begin with a font structure and then are followed by four character 
arrays: 

/♦ characteristics of a font ♦/ 
/♦ number of width entries ♦/ 
/♦ 1 == special font ♦/ 

/* 1 s= ligatures exist on this font */ 
/♦ name of this font, e.g., R */ 
/♦ internal name of font, in ASCII */ 



{ 



struct Font 
char nwfont; 

specf ont ; 

ligf ont ; 
namef ont [10]; 
intname[ 10 ] ; 



char 
char 
char 
char 

) ; 
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The font structure tells how many defined characters there are in the font, 
whether the font is a "special" font and if it contains ligatures. It also has the 
ASCII name of the font, which should match the name of the file it appears 
in, and the internal name of the font on the typesetting device (intname). The 
internal name is independent of the font position and name that troff knows 
about. For example, you might say mount R in position 4, but when asking 
the typesetter to actually produce a character from the R font, the postproces- 
sor which instructs the typesetter would use intname. 

The first three character arrays are specific for the font and run in parallel 
The first array, widths, contains the width of each character relative to 
umtwidth, unitwidth is defined in DESC. The second array, kerning, contains 
kerning information. If a character rises above the letter 'a', 02 is set If it 
descends below the line, 01 is set. The third array, codes, contains the code 
that IS sent to the typesetter to produce the character. 

The fourth array is defined by the device description in DESC. It is the 
font index Jable. This table contains indices into the width, kerning, and code 
tables for each character. The order that characters appear in these three 
tables is arbitrary and changes from one font to the next. In order for troff to 
be able to translate from ASCII and the special character names to these arbi- 
trary tables, the font Jndex Jable is created with an order that is constant for 
each device. The number of entries in this table is 96 plus the number of spe- 
cial character names for this device. The value 96 is 128 - 32, the number of 
characters in the ASCII alphabet. To determine whether a normal 
ASCII character exists, troff takes the ASCII value of the character, subtracts 
32 and looks in the font Jndex Jable. If it finds a 0, the character is not 
defined in this font. If it finds anything else, that is the index into widths, 
kerning, and codes that describe that character. 

To look up a special character name, for example \(pl, the mathematical plus 
sign, and determine whether it appears in a particular font or not, the follow- 
ing procedure is followed. A counter is set to and an index to a special char- 
acter name is picked out of the counter'th position in the funny j:har Jndex Jable. 
A string comparison is performed between funny j:har strings [ 
funny char Jndexjable I counter ] } and the special character name, in"our exam- 
ple pi, and if it matches, then troff refers to this character as ( 96 + counter) 
When it wants to determine whether a specific font supports this character it 
looks in f ont Jndex Jablem+counter)], (see below), to see whether there is a 
meaning the character does not appear in this font, or a number, which is the 
index into the widths, kerning, and codes tables. 

Notice that since a value of in the font index Jable shows that a character 
does not exist, the 0th element of the width, kerning, and codes arrays are not 
used. For this reason the 0th element of the width array can be used for a spe- 
cial purpose, defining the width of a space for a font. Normally a space is 
defined by troff to be 1/3 of the width of the \(em character, but if the 0th 
element of the width array is non-zero, then that value is used for the width 
of a space. 

SEE ALSO 

troff(l), troff (5). 
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FILES 

/usr/lib/font/devffyJype/DESC.out description file for phototypesetter tty_type 

/usr/lib/font/devffi/Jype//o«f.out font description files for phototypesetter ttyjype 
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NAME 

grap - pic preprocessor for drawing graphs 
SYNOPSIS 

grap I-Tttyjype ] [ -I ] [ — ] [ file(s) ] 
OPTIONS 

-T Specifies Uyjype as grap's output device. Currently supported 
devices are aps (Autoiogic APS-5) and dilO (Imagen Imprint 
10). -Taps is default. 

-1 Stops grap from looking for a library file of macro defines, 
/usr/lib/dwb/grap.defines, 

DESCRIPTION 

grap is a language for typesetting graphs. It is also the name of a preproces- 
sor that feeds input to pic(l). Thus, a typical command line would appear as 
follows: 



grap file($) \ pic | troff | typesetter 

Graphs are surrounded by the troff "commands" .01 and .G2. Data that is 
enclosed is scaled and plotted, with tick marks supplied automatically. Com- 
mands exist to modify the frame, add labels, override the default ticks, change 
the plotting style, define coordinate ranges and transformations, and include 
data from files. In addition, grap provides the same loops, conditionals and 
macro processing that pic does, 

FILES 

/usr/lib/dwb/grap.defines: definitions of standard plotting characters, e.g., 
bullet. 

SEE ALSO 

pic(l). 
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NAME 

hyphen - find hyphenated words 

SYNOPSIS 

hyphen [ file(s) ] 

DESCRIPTION 

hyphen finds all the hyphenated words ending lines in fileis) and prints them 
on the standard output. If no arguments are given or if hyphen encounters 
— , it uses the standard input. Thus, hyphen may be used as a filter. 

EXAMPLE 

You would use the following command-line to proofread nroff's hyphenation 
in file(s): 

mm tntn opiionis) filets) | hyphen 

SEE ALSO 

mm(l), troff(l). 

BUGS 

hyphen can't cope with hyphenated italic (or underlined words); it frequently 
will either miss them altogether or mishandle them, hyphen occasionally 
gets confused but with no ill effects other than spurious extra output. 
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NAME 

macref - produces cross-reference listing of macro files 

SYNOPSIS 

macref [-t] [-s] [-n] [ - - ] file(s) 

DESCRIPTION 

macref reads the named file(s) (which are assumed to be nroff(l) or troff(l) 
input) and produces a cross-reference listing of the symbols in the input. 

A — t on the command line causes a macro table of contents to be printed. 
The option — s causes symbol-use statistics to be printed. The option — n 
causes one line to be printed for each reference to a symbol. The options may 
be grouped behind one — , You may use *' — " to delimit the end of options, 
macref does not accept — as standard input. 

The default output is a list of the symbols found in the input, each accom- 
panied by a list of all references to that symbol, macref lists the symbols 
alphabetically in the leftmost column, with the references following to the 
right. Each reference is given in the form: 



where the fields have the following meanings: 

Mname the name of the macro within which the reference occurs. This field 
is missing if the reference occurs outside a macro. Any names listed 
in the NMname part are macros within which Mname is defined. 



s string 

n number register 

p parameter (e.g., \$x is a parameter reference to x. Note that 
parameters are never modified, and that the only valid param- 
eter symbol names are 1, 2, ... 9). 



[ [(NMname)] Mname-] type Inum [#] 



type 



the type associated, by context, with this occurrence of the symbol. 
The types may be: 
r request 
m macro 
d diversion 



Inum 



the line number on which the reference occurred. 



# 



this reference modifies the value of the symbol. 



Generated names are listed under the artificial symbol name "'sym". 



SEE ALSO 



nroff(l), troff(l), mm(l), mm(5), mv(5), mmt(l), mvt(l), and man(5). 



REFERENCE MANUAL 1 



MAN(5) 



MAN(5) 



NAME 

man — macros for formatting entries in this manual 

SYNOPSIS 

nroff —man file(s) 

troff -man [ -rsl ] file(s) 

DESCRIPTION 

These nroff/troff macros are used to lay out the format of the entries of this 
manual. The default page size is 8.5"xll", with a 6.5"xl0" text area; the -rsl 
option reduces these dimensions to 6"x9" and 4.75"x8.375", respectively; this 
option also reduces the default type size from 10-point to 9-point, and the 
vertical line spacing from 12-point to 10-point. The -rV2 option may be used 
to set certain parameters to values appropriate for certain Versatec printers: it 
sets the line length to 82 characters, the page length to 84 lines, and it inhi- 
bits underlining. 

Any text argument below may be one to six "words." Double quotes (*"*) may 
be used to include blanks in a "word." If text is empty, the special treatment 
is applied to the next line that contains text to be printed. For example, .1 
may be used to italicize a whole line, or .SM followed by .B to make small 
bold text. By default, hyphenation is turned off for nroff(l), but remains on 
for troff(l). 

Type font and size are reset to default values before each paragraph and after 
processing font- and size-setting macros, for example, .1, .RB, .SM. Tab stops 
are neither used nor set by any macro except .DT and .TH. 

Default units for indents in are ens. When in is omitted, the previous indent 
is used. This remembered indent is set to its default value (7.2 ens in troff(l), 
5 ens in nroff(l)) by .TH, .P, and .RS, and restored by .RE. 

.TH t sc n Set the title and entry heading; t is the title, s is the section 
number, c is extra commentary, e.g., "local", n is new manual 
name. Invokes .DT (see below). 

.SH text Place subhead text, for example, SYNOPSIS, here. 

.SS text Place sub-subhead text, for example. Options, here. 

.B text Make text bold. 

.1 text Make text italic. 

.SM text Make text 1 point smaller than default point size. 

.RI a b Concatenate roman a with italic b, and alternate these two fonts 

for up to six arguments. Similar macros alternate between any 

two of roman, italic, and bold: 
.IR .RB .BR .IB .BI 
.P Begin a paragraph with normal font, point size, and indent. .PP is 

a synonym for the mm(5) macro .P. 
.HP in Begin paragraph with hanging indent. 

•TP in Begin indented paragraph with hanging tag. The next line that 
contains text to be printed is taken as the tag. If the tag does not 
fit, it is printed on a separate line. 

.IP t in Same as .TP in with tag t; often used to get an indented paragraph 
without a tag. 
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.RS in Increase relative indent (initially zero). Indent all output an extra 

in units from the current left margin. 
.REk Return to the ^rth relative indent level (initially, jt-0 is 

equivalent to ^-1); if k is omitted, return to the most recent lower 

indent level. 

.PM m Produces proprietary markings see REFERENCE to nim(l) below. 
.DT Restore default tab settings (every 7.2 ens in troff(l), 5 ens in 

nroff(l)). 

.PD V Set the interparagraph distance to u vertical spaces. If v is omit- 
ted, set the interparagraph distance to the default value (0,4v in 
tro£f(l), Iv in nroff(l)). 

The following strings are defined: 

VR ® in tro£f(l), (Reg.) in nroff, 

\»S Change to default type size. 

\*<Tin Trademark indicator. 

The following number registers are given default values by .TH: 

IN Left margin indent relative to subheads (default is 7.2 ens in 

tro£f(I), 5 ens in nro£f(l)). 
LL Line length including IN. 

PD Current interparagraph distance. 

EXAMPLES 

The man macros are provided to process manual pages already on-line at a 
given location and to enable users to make their own manual pages. The 
preceding section demonstrated the usage of the macros themselves; the fol- 
lowing section provides examples of command lines typically used to process 
the completed files. 

man macros are designed to run with either nroff or troff. The first com- 
mand line will process file(s) using only macros and nroff requests: 

nrotf -Tip -man file(s) | Ip 

File(s) is piped to the local line printer, Ip. 

The next command line will process file(s) containing tables as well as macros 
and nroff requests: 

tbl fUe(s) I nroff -Tip -man | col | Ip 

Notice that before it is sent to the line printer, the output is first filtered 
through col, to process the reverse line feeds used by tbl. 

The final example is a command line that processes an unusual manual page, 
one using pic and grap. If the manual pages created with man are intended 
for an on-line facility, components requiring troff, such as grap or pic, should 
be avoided since the average installation of terminals will not be able to pro- 
cess typeset documents. 

grap file(s) | pic | tbl | troff -Taps -man | typesetter 
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grap precedes pic because it is a preprocessor to pic; the reverse order will not 
format correctly, File(s) contains one or more tables, requiring tbl, but col is 
no longer necessary because typeset documents do not use reverse line feeds 
with which to make tables. The -T option for specifying the output device 
(Terminal type) takes the argument aps here, readying the document for pro- 
cessing on the APS-5 phototypesetter. 

SEE ALSO 

eqn(l), man(l), neqn(l), nro£f(l), tbl(l). tc(l), troff(l). 
The "mm; Technical Discussion" 

FILES 

/ usr / lib / tmac / tmac*an 

/ usr / lib / macros /an 

/ usr / man / [uap]_man / manO /skeleton 

CAVEATS 

Special macros, strings, and number registers exist, internal to man, in addi- 
tion to those mentioned above. Except for names predefined by troff(l) and 
number registers d, m, and y, all such internal names are of the form XA, 
where X is one of ), \ and ], and A stands for any alphanumeric character. 
User defined macros should avoid these naming conventions. 

The programs that prepare the Table of Contents and the Permuted Index for 
this manual assume the NAME section of each entry consists of a single line of 
input that has the following format: 

name \— explanatory text 

The macro package increases the inter-word spaces (to eliminate ambiguity) in 
the SYNOPSIS section of each entry. 

The macro package itself uses only the roman font (so that one can replace, 
for example, the bold font by the constant-width font (CW). Of course, if the 
input text of an entry contains requests for other fonts (for example, .1, .RB, 
\fl), the corresponding fonts must be mounted. 

BUGS 

If the argument to .TH contains any blanks and is not enclosed by double 
quotes (""), there will be strange irregular dots on the output. 
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NAME 



mm — prints documents formatted with the mm macros 



SYNOPSIS 

mm [ option(s) ] [ file(s) ] 

DESCRIPTION 

Use mm to format documents using nroff and the mm text-formatting macro 
package, mm has options to specify preprocessing by tbl(l) and/or neqn(l), 
and postprocessing by various terminal-oriented output filters. The proper 
pipelines and the required arguments and flags for nroff and mm are gen- 
erated, depending on the options that you select. 

Options for mm are given below. Any other arguments or flags (e.g., -rC3) 
are passed to nroff as appropriate. You may use such options in any order, 
but you must put them before the fileis) arguments. If you do not specify 
arguments, mm prints a list of its options. 

-Tttyjype 

specifies the type of output terminal. 

Here is a list of recognized values for ttyjype, 

2631 Hewlett-Packard 2631 printer in regular mode 
2631-c Hewlett-Packard 2631 printer in compressed mode 
2631-e Hewlett-Packard 2631 printer in expanded mode 
300 DASI-300 printer 

300-12 DASI-300 terminal set to 12-pitch (12 characters per 
inch) 

3008 DASI-300S printer (3008 is a synonym) 

300S-12 DASI-300S printer set to 12-pitch (12 characters per 

inch) (300S-12 is a synonym) 
37 Teletype Model 37 terminal 

382 DTC-382 

4000a Trendata 4000a terminal (4000A is a synonym) 
450 DASI-450 (Diablo Hyterm) printer 

450-12 DASI-450 terminal set to 12-pitch (12 characters per 
inch) 

832 Anderson Jacobson 832 terminal 

8510 C.ITOH printer 
tn300 GE Terminet 300 terminal 
X printers equipped with TX print train 

Ip generic name for printers that can underline and 

tab.lp is the default device for mm.All text sent to Ip 
requiring reverse linefeeds, such as those having 
tables,must be processed with col, invoked with mm's 
— c option. Ifyou do not use this option, mm uses the 
value of the shellvariable $TERM from the environ- 
ment (see profile(4) and environ(5)) as the value of 
ityjypeii STERM is set; otherwise, mm uses 450 as the- 
value of ttyjype. If you specify several terminal 
types,the last one takes precedence. 
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(Check with your system administrator for a list of locally sup- 
ported devices.) 

indicates that the document is to be produced in 12-pitch. You may 
use this option when $TERM is set to one of 300, 300s, and 450. 
(You must manually set the pitch switch on the DASI 300 and 300s 
terminals to 12 if you use this option.) 

causes mm to invoke col(l); note that col(l) is invoked automatically 
by mm unless ttyjype is one of 300, 300s, 450, 37, 4000a, 382, and X. 
causes mm to invoke neqn; also causes neqn to read the 
/usr/pub/eqnchar Hie (see eqnchar(5)). 
causes mm to invoke tbl(l). 
invokes the -e option of nroff. 

As an example, assume that the shell variable $TERM is set in the environ- 
ment to 450. The two command lines below are then equivalent: 

mm -t -rC3 -12 file($) 

tbl file(s) I nro£f -mm -T450-12 -h -rC3 

mm reads the standard input when you specify - instead of any fileis), (Men- 
tioning other Eles together with - leads to undesired results.) This option 
allows you to use mm as a filter, for example: 

cat file(s) \ mm - 

HINTS 

1. mm invokes nroff with the -h flag. With this flag, nroff assumes that 
the terminal has tabs set every 8 character positions. 

2. Use the -o/isf option of nroff to specify ranges of pages to be output. 
Note, however, that if you invoke mm with one or more of the -e, 
-t, and - options, together with the -o/isf option of nroff, you may 
cause a harmless "broken pipe" diagnostic if you do not specify the 
last page of the document in list, 

3. If you use the -s option of nroff (to stop between pages of output), 
use line-feed (rather than return or new-line) to restart the output. 
The -8 option of nroff does not work with the -c option of mm, or if 
mm automatically invokes col(l) (see -c option above). 

4. If you lie to mm about the kind of terminal its output will be printed 
on, you will get (often subtle) garbage; however, if you are redirecting 
output into a file, use the -T37 option, and then use the appropriate 
terminal filter when you actually print that file. 

FILES 

/usr/pub/terminals list of supported terminals 
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SEE ALSO 

checkmin(l), col(l), env(l), eqn(l), greek(lX mmt(l), nivt(l), neqn(l), 

nrotf(l), tbl(l), profile(4), mm(5), and term(5). 

The "mm: Technical Discussion" 

"The Macro Package mm" in the User's Guide. 
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NAME 

mm - the mm macro package for formatting documents 

SYNOPSIS 

mm [ opiionis) ] [ jileis) ] 

nroff [ option(s) ] -mm [ file(s) ] 

mmt [ option(s) ] [ file(s) ] 

troff [ option(s) ] -mm [ file(s) ] 

DESCRIPTION 

This package provides a formatting capability for a very wide variety of docu- 
ments. The manner in which you type and edit a document is essentially 
independent of whether the document is to be eventually formatted at a ter- 
minal or is to be phototypeset. 

FILES 

/usr/lib/tmac/tmac.m pointer to the mm package 

/usr/lib/macros/mm[nt] the mm package 

SEE ALSO 

mm(l), mmt(l), nroff(l), and troff(l). 

"mm: Technical Discussion." 

"The Macro Package mm" in the User's Guide. 
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NAME 

mmt - typeset documents 

SYNOPSIS 

mmt [ option(s) ] [ file(s) ] 

DESCRIPTION 

This command is similar to mm(l), except that it typesets its input via tro£f(l), 
as opposed to formatting it via nroff(l); mmt uses the mm macro package. 
There are options to specify preprocessing by tbl(l) and/or pic(l) and/or 
eqn(l) and/or grap(l). The proper pipelines and the required arguments and 
flags for troff(l) and for the macro package are generated, depending on the 
options selected. 

Option(s) specific to mmt are given below. Any other arguments or flags (e.g., 
-rC3) that you give mmt are passed to troff(l). You can put options in any 
order, but they must appear before any file(s). If you give no arguments or 
files, mmt prints a list of its options. 

— e invokes eqn(l); also causes eqn to read the 

/usr/pub/eqnchar file (see eqnchar(5)). 
— t invokes tbl(l). 

— p invokes pic(l). 

-g invokes grap(l), which in turn calls pic(l). 

-Ttty type creates output for troff device ttyjype (see tro££(l)). The 

output is sent through the appropriate postprocessor (see 

dapsd)). ' , . 

-Ddest directs the output to device dest. Supported values for 

dest are: 4014 (TEKTRONIX 4014 terminal via the tc(l) 
filter); and ilO (Imagen Imprint-10 laser printer via 
dilO(l) filter. 

-z invokes no output filter to process or redirect the output 

of troffd). 

mmt reads the standard input when you specify - instead of any files, 

HINT 

Use the -o/isf option of troff(l) to specify ranges of pages to be output. Note, 
however, that if you call mmt with one or more of the -e, -t, -p, -g, and - 
options together with the -o/isf option of troff(l), you may cause a harmless 
"broken pipe" diagnostic if the last page of the document is not specified in 
list. 
SEE ALSO 

daps(l), dilO(l), eqn(l), grap(l), mm(l), mvt(l), pic(l), tbl(l), tc(l), tro£f(l), 
eqnchar(5), mm(5). 
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NAME 

mptx - the macro package for formatting a permuted index 
SYNOPSIS 

nroff -mptx [ option(s) ] ple(s) \ printer 
troff -mptx [ option(s) ] file(s) \ typesetter 
DESCRIPTION 

This package provides a definition for the .xx macro used for formatting a per- 
muted index as produced by ptx(l). This package does not provide any other 
formatting capabilities such as headers and footers. If these or other capabili- 
ties are required, the mptx macro package may be used in conduction with the 
mm macro package. In this case, the -mptx option must be invoked after the 
-mm call. For example, 

nroff -mm -mptx file(s) \ printer 

or 

mmt -mptx file($) \ typesetter 

FILES 

/U8r/lib/tmac/tmac*ptx pointer to the macro package 
/usr/Iib/macros/ptx* macro package 

SEE ALSO 

mm(l), nroff(l), ptx(l), troff(l), mm(5). 
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NAME 

mv - a troff macro package for typesetting view graphs and slides 

SYNOPSIS 

mvt [ -a ] [ option(s) ] [ fileis) ] 

troff [ -a ] [ -rXl ] -mv [ optionis) ] [ file(s) ] 

DESCRIPTION 

This package makes it easy to typeset view graphs and projection slides in a 
variety of sizes. A few macros (briefly described below) accomplish most of 
the formatting tasks needed in making transparencies. All of the facilities of 
tro£f(l), eqn(l), tbl(l), pic(l), and grap(l) are available for more difficult tasks. 
The output can be previewed on most terminals, and, in particular, on the 
TEKTRONIX 4014. For this device, specify the -rXl option (this option is 
automatically specified by the mvt command when that command is invoked 
with the -D4014 option). To preview output on other terminals, specify the 
—a option. 

The available macros are: 

•VS Foil-start macro; foil size is to be 7"x7"; n is the foil 

number, i is the foil identification, d is the date; the foil- 
start macro resets all parameters (indent, point size, etc.) to 
initial default values, except for the values of i and d argu- 
ments inherited from a previous foil-start macro; it also 
invokes the .A macro (see below). 

The naming convention for this and the following eight 
macros is that the first character of the name (V or S) distin- 
guishes between view graphs and slides, re.spectively, while 
the second character indicates whether the foil is square (S), 
small wide (w), small high (h), big wide (W), or big high 
(H), Slides are "skinnier" than the corresponding view 
graphs: the ratio of the longer dimension to the shorter one 
is larger for slides than for view graphs. As a result, slide 
foils can be used for view graphs, but not vice versa; on the 
other hand, view graphs can accommodate a bit more text. 

.Vw [n] [i] {d\ Same as .VS, except that foil size is 7" wide x 5" high. 

.Vh [w] [i] [d] Same as *VS, except that foil size is 5"x7",^^ 

.VW [n] [0 \d\ Same as .VS, except that foil size is 7"x5-4". 

.VH [n] [i] [d] Same as .VS, except that foil size is 7"x9". 

.Sw [n] [i] [d] Same as .VS, except that foil size is 7"x5". 

.Sh [m] [i] [d] Same as .VS, except that foil size is 5" x7". 

.SW [w] [i] [d\ Same as .VS, except that foil size is 7"x5.4". 

.SH [n] [li [d\ Same as .VS, except that foil size is 7"x9". 

.A \x\ Place text that follows at the first indentation level (left 

margin); the presence of x suppresses the ^/i line spacing 
from the preceding text. 

•B [m [s] ] Place text that follows at the second indentation level; text 
is preceded by a mark; m is the mark (default is a large bul- 
let); s is the increment or decrement to the point size of the 
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mark with respect to the prevailing point size (default is 0); 
if s is 100, it causes the point size of the mark to be the 
same as that of the default mark. 
.C [m [s] ] Same as .B, but for the third indentation level; default mark 
is a dash. 

.D [m[s]] Same as .B, but for the fourth indentation level; default 
mark is a small bullet. 

.T string String is printed as an over-size, centered title. 

.1 [in] [a [x] ] Change the current text indent (does not affect titles); in is 
the indent (in inches unless dimensioned, default is 0); if in 
is signed, it is an increment or decrement; the presence of a 
invokes the .A macro (see below) and passes x (if any) to it. 

•S [p][l] Set the point size and line length; p is the point size 

(default is "previous"); if p is 100, the point size reverts to 
the initial default for the current foil-start macro; if p is 
signed, it is an increment or decrement (default is 18 for 
.VS, .VH, and .SH, and 14 for the other foil-start macros); / 
is the line length (in inches unless dimensioned; default is 
4.2" for .Vh, 3.8" for .Sh, 5" for .SH, and 6" for the other 
foil-start macros). 

.DF n f [n f .,.] Define font positions; may not appear within a foil's input 
text (i.e., it may only appear after all the input text for a 
foil, but before the next foil-start macro); n is the position of 
font /; up to four "« /" pairs may be specified; the first font 
named becomes the prevailing font; the initial setting is (H is 
a synonym for G): 

.DF 1 H 2 I 3 B 4 S 
.DV [a] [b] [c] [d] Alter the vertical spacing between indentation levels; a is 
the spacing for .A, b is for .B, c is for .C, and d is for .D; all 
non-null arguments must be dimensioned; null arguments 
leave the corresponding spacing unaffected; initial setting is: 
.DV .5v .5v ,5v Ov 
.U strl [str2] Underline strl and concatenate str2 (if any) to it. 
The last four macros in the above list do not cause a break; the .1 macro causes 
a break only if it is invoked with more than one argument; all the other mac- 
ros cause a break. 

The macro package also recognizes the following upper-case synonyms for the 
corresponding lower-case troff requests: 

.AD .BR .CE .FI .HY .NA .NF .NH .NX .SO .SP .TA .TI 



FILES 



The Tm string produces the trademark symbol. 
See the reference cited below for further details. 

/ usr / lib / tmac / tmac. v 
/ usr/ lib/ macros /vmca 
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SEE ALSO 

eqn(l), grap(l), mvt(l), pic(l), tbl(l), tro££(l). 
The Macro Package mv" in the User's Guide, 

BUGS 

The .VW and .SW foils are meant to be 9" wide by 7 high, but because the 
typesetter paper is generally only 8" wide, they are printed 7" wide by 5.4" 
high and have to be enlarged by a factor of 9/7 before use as view graphs; this 
makes them less than totally useful. 
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NAME 

mvt — typeset view graphs and slides 

SYNOPSIS 

mvt [ option(s) ] [ file(s) ] 

DESCRIPTION ^ . . - 

This command is similar to mmt(l), except that it typesets its input with the 
mv macro package for view graphs and slides, mvt has options to specify 
preprocessing by tbl(l) and/or pic(l) and/or eqn(l) and/or. grap{l). The 
proper pipelines and the required arguments and flags for trotf(l) and for the 
macro package are generated, depending on the options selected. 
Option(s) specific to mvt are given below. Any other arguments or flags that 
you give mvt are passed to troff(l). Options can occur in any order, but they 
must appear before any fileis). If you give no arguments or file(s), mvt prints 
a list of its options. 

_e invokes eqn(l); also causes eqn to read the 

/usr/pub/eqnchar file (see eqnchar(5)). 
— t invokes tbl(l). 

— p invokes pic(l). 

_g invokes grap(l), which in turn calls pic(l). 

-Tttyjype creates output for troff device ttyjype (see trof£(l)). The 

output is sent through the appropriate postprocessor (see 
daps(l)). ^ ■ ^ 

~T>de$t directs the output to device dest. Supported values for 

dest are: 4014 (TEKTRONIX 4014 terminal via the tc(l) 
filter); and ilO (Imagen Imprint-10 laser printer via 
dilO(l) filter.) 

_z invokes no output filter to process or redirect the output 

of tro££(l). 

mvt reads the standard input when you specify - instead of any file(s). 

HINT ^ . , ^ 

Use the -olist option of troff(l) to specify ranges of pages to be output. Note, 
however, that if you invoke mvt with one or more of the — e, -t, -p, -g, and 
- options together with the -olist option of troff(l), you may cause a harm- 
less "broken pipe" diagnostic if the you do not specify the last page of the 
document in list, 

SEE ALSO 

daps(l), dilO(l), eqn(l), grap(l), mmt(l), pic(l), tbl(l), tc(l), troff(l), 
eqnchar(5), mv(5). 
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NAME 

ndx - create a subject-page index for a document 
SYNOPSIS 

ndx [subjfile] "formatter command line" 

DESCRIPTION ^ ^ ^ ^ 

ndx, given a list of subjects (subjfile), searches a specified document and writes 
a subject-page index to the standard output. 

subjfile is the list of subjects to be included in the index. Each subject must 
begin on a new line and have the following format: 

wordl [word2 ,..] [, wordk ...] 

For example, 

printed circuit boards 
arrays 

arrays, dynamic storage 
Smith, W. P. 

printed circuit boards, channel-oriented multi-layer 
Aranoff 

University of Illinois 
PL/1 

The subject must start in column 1. 

The syntax for the formatter command line is 

formatter [ option(s) ] file(s) 

It is the command that will be used to create the final form of the document. 
The following are examples of valid formatter command lines: 

mm -Tip file(s) 

nroff -mm -Tip -rW60 file(s) 
troff -rB2 -Taps -rOl.Si file(s) 

For more information on the formatter command line, see, mm(lX mmt(l), 
nro£f(l) and troff(l). 

The document must include formatting commands for mm, nroff, or troff. 
The formatter command line tells ndx whether troff, nroff, mm or mmt 
would be used to produce the final version of the document, 
troff or mmt 

specifies troff as the formatting program, 
nroff or mm 

specifies nroff as the formatting program 
The option(s) are those that would be given to the troff, nroff, mm or 
mmt command in printing the final form of the document, and are 
necessary to determine the correct page numbers for subjects as they 
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are located in the document, ndx does not actually cause the final 
version of the document to be printed. The author must create the 
document separately. The indexer, of course, should not be used until 
the document is complete and no further changes are expected. 

EXAMPLES 

The cominand 

ndx subjfile "nroff -mm -rW70 file(s)'' > indexfile 

would produce a subject-page index for the document file($) and take its sub- 
jects from the list, subjfile. The page numbers would correspond to the docu- 
ment produced by 

nroff -mm -rW70 fHe(s) 
The command 

ndx subjfile "mm -rW60 -rN2 -rOO chl ch2 ch3" > ittdexfile 

would produce a subject-page index for the documents chl, ch2, and ch3. The 
page numbers would correspond to the documents produced by 

mm -rW60 -rN2 -rOO chl ch2 ch3 

The command 

ndx subjfile "troff -rB2 -rW5i -rOl.Si -mm fileisr > indexfilc 

would produce a subject-page index for the document file($K and the page 
numbers would correspond to the document produced by 

troff -rB2 -rW5i -rOl.Si -mm filc(s) 

SEE ALSO 

mm(l), mmt(lX nroff(l), subj(l), troff(l). 
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NAME 

neqn — format mathematical text for nro£f 
SYNOPSIS 

neqn [ -d ] [ -p n ] [ -s n ] [ -f n ] [ — ] [ file(s) ] 
DESCRIPTION 

neqn is a preprocessor for formatting mathematical text with nroff on 
typewriter-like terminals. Normal usage is: 

neqn [option(s)] file(s) \ nroff [option(s)] \ \printer] 
If you do not specify files (or if you specify - as the last argument), neqn 
reads the standard input. 

SEE ALSO 

eqn(l), mm(l), nro£f(l), tbl(l), eqnchar(5), and mm(5). 
"The Preprocessor eqn" in the User's Guide. 
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NAME 

nroff - text formatting language 
SYNOPSIS 

nroff [ option(s) ] [ file(s) ] \ printer 
DESCRIPTION 

nroff formats text contained in file($) (standard input by default) for printing 
on typewriter-like devices and line printers. 

An argument consisting of a minus (-) is taken to be a file name correspond- 
ing to the standard input. The option($), which may appear in any order, but 
must appear before the file(s), are, 

-olist Print only pages whose page numbers appear in the list of numbers 
and ranges, separated by commas. A range N-M means pages N 
through M; an initial -N means from the beginning to page N; and 
a final N- means from N to the end. (See BUGS below.) 

-nN Number first generated page N. 

-sN Stop every N pages, nroff will halt after every N pages (default 
]s/=i) to allow paper loading or changing, and will resume upon 
receipt of a line-feed or new-line (new-lines do not work in pipe- 
lines, e.g., with mm(l)). This option does not work if the output of 
nroff is piped through col(l). When nroff halts between pages, an 
ASCII BEL is sent to the terminal. 

-raN Set register a (which must have a one-character name) to N . 

-1 Read standard input after file(s) are exhausted. 

-q Invoke the simultaneous input-output mode of the .rd request. 

-z Print only messages generated by .tm (terminal message) requests. 

-mname Prepend to the input file(s) the macro file /usr/lib/tmac/tmac.nflme. 

-Ttty type 

Prepare output for specified terminal. Known ttyjype(s) are 



2631 Hewlett-Packard 2631 printer in regular mode 

2631-c Hewlett-Packard 2631 printer in compressed mode 
2631-e Hewlett-Packard 2631 printer in expanded mode 
300 DASI-300 printer 

300-12 DASI-300 terminal set to 12-pitch 

(12 characters per inch) 
300s DASI-300S printer (300S is a synonym) 

300S-12 DASI-300S printer set to 12-pitch 

(12 characters per inch) 

(300S-12 is a synonym) 
37 Teletype Model 37 terminal (default) 

382 DTC-382 

4000a Trendata 4000a terminal (4000A is a synonym) 

450 DASI-450 (Diablo Hyterm) printer 

450-12 DASI-450 terminal set to 12-pitch 

(12 characters per inch) 
832 Anderson Jacobson 832 terminal 

8510 C.ITOH printer 

Ip generic name for printers that can 
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underline and tab (All text using reverse 
line feeds, such as those having tables, 
that is sent to Ip must be processed 
with col.) 

tn300 GE Terminet 300 terminal 

X printers equipped with TX print train 



— e 



FILES 



Produce equally-spaced words in adjusted lines, using the full reso- 
lution of the particular terminal, 
-h Use output tabs during horizontal spacing to speed output and 
reduce output character count. Tab settings are assumed to be every 
8 nominal character widths. 
-u« Set the emboldening factor (number of character overstrikes) for the 
third font position (bold) to n, or to zero if n is missing. 



/usr/lib/tmac/tmac* pointers to standard macro Hies 
/usr/lib/macros/^ standard macro files 
/usr/lib/nterm/* terminal driving tables for nroff 
/usr/pub/tenninals list of supported terminals 
SEE ALSO 

col(l), neqn(l), greek(l), mm(l), mm(5), tbl(l). 
The "nroff/troff: Technical Discussion." 
The Formatter nroff" in the User's Guide. 



BUGS 



nroff believes in Eastern Standard Time; as a result, depending on the time of 
the year and on your local time zone, the date that nroff generates may be off 
by one day from your idea of what the date is. 

When nroff is used with the -oUst option inside a pipeline (e.g., with one or 
more of eqn(l), and tbl(l)), it may cause a harmless "broken pipe" diagnostic if 
the last page of the document is not specified in list. 
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NAME 

nterm - terminal driving tables for nroff 
DESCRIPTION 

nroff (1) uses driving tables to customize its output for various types of output 
devices, such as printing terminals, special word-processing terminals (such as 
Diablo, Qume, or NEC Spinwriter mechanisms), or special output filter pro- 
grams. These driving tables are written as ASCII files, and are installed in 
/usr/lib/nterm/tab.nflme, where name is the name for that terminal type as 
given in term(5). 

The first line of a driving table should contain the name of the terminal: sim- 
ply a string with no embedded white space. "White space" means any combi- 
nation of spaces, tabs and new-lines. The next part of the driver table is 
structured as follows: 

bset [integer] (not supported in all versions of nroff) 

breset [integer] (not supported in all versions of nroff) 

Hot [integer] 

Vert [integer] 

Newline [integer] 

Char [integer] 

Em [integer] 

Halfline [integer] 

Adj [integer] 

twinit [character string] 

twrest [character string] 

twnl [character string] 

hlr [character string] 

hlf [character string] 

fir [character string] 

bdon [character string] 

bdoff [character string] 

iton [character string] 

itoff [character string] 

ploton [character string] 

plotoff [character string] 

up [character string] 

down [character string] 

right [character string] 

left [character string] 

The meanings of these fields are as follows: 

bset bits to set in the c_oflag field of the termio structure before output, 

breset bits to reset in the c_oflag field of the termio structure before out- 
put. 

Hor horizontal resolution in units of 1/240 of an inch. 
Vert vertical resolution in units of 1/240 of an inch. 
Newline space moved by a newline (linefeed) character in units of 1/240 of 
an inch. 
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Char quantum of character sizes, in units of 1/240 of an inch, (i.e., a 
character is a multiple of Char units wide) 

Em size of an em in units of 1/240 of an inch. 

Halfline space moved by a half-linefeed (or half-reverse-iinefeed) character 
in units in 1/240 of an inch. 

Adj quantum of white space, in 1/240 of an inch, (i.e., white spaces are 

a multiple of Adj units wide) 

Note: if this is less than the size of the space character, rtroff will 
output fractional spaces using plot mode. Also, if the -e switch to 
nroff is used, Adj is set equal to Hor by nroff, 

sequence of characters used to initialize the terminal in a mode 
suitable for nroff. 

sequence of characters used to restore the terminal to normal mode. 

sequence of characters used to move down one line. 

sequence of characters used to move up one-half line. 

sequence of characters used to move down one-half line. 

sequence of characters used to move up one line. 

sequence of characters used to turn on hardware boldface mode, if 
any. 

sequence of characters used to turn off hardware boldface mode, if 
any. 

sequence of characters used to turn on hardware italics mode, if 
any, 

sequence of characters used to turn off hardware italics mode, if 
any. 

sequence of characters used to turn on hardware plot mode (for 
Diablo type mechanisms), if any. 

sequence of characters used to turn off hardware plot mode (for 
Diablo type mechanisms), if any. 

sequence of characters used to move up one resolution unit (Vert) 
in plot mode, if any. 

sequence of characters used to move down one resolution unit 
(Vert) in plot mode, if any. 

sequence of characters used to move right one resolution unit (Hor) 
in plot mode, if any. 

sequence of characters used to move left one resolution unit (Hor) 
in plot mode, if any. 

This part of the driving table is fixed format, and you cannot change the order 
of entries. You should put entries on separate lines, and these lines should 
contain exactly two fields (no comments allowed) separated by white space. 
For example. 



twinit 

twrest 

twnl 

hlr 

hlf 

fir 

bdon 

bdoff 

iton 

itoff 

ploton 

plotoff 

up 

down 
right 
left 
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bset 
breset 
Hor 2- 



24 



and so on. 

Follow this first part of the driving table with a line containing the word 
"charset/' and then specify a table of special characters that you want to 
include. That is, specify all the non-ASCII characters that nroff(l) knows by 
two character names, such as \(hy. If nroff does not find the word "charset" 
where it expects to, it will abort with an error message. 

Each definition in the part after "charset" occupies one line, and has the fol- 
lowing format: 



where "chname" is the (two letter) name of the special character, "width" is 
its width in ems, and "output" is the string of characters and escape sequences 
to send to the terminal to produce the special character. 

If any field in the "charset" part of the driving table does not pertain to the 
output device, you may give that particular sequence as a null string, or leave 
out the entry. Special characters that do not have a definition in this file are 
ignored on output by nroff(l). 

You may put the "charset" definitions in any order, so it is possible to speed 
up nroff by putting the most used characters first. For example. 



and so on. 

The best way to create a terminal table for a new device is to take an existing 
terminal table and edit it to suit your needs. Once you create such a file, put 
it in the directory / usr/ lib /n term, and give it the name tab.xyz where xyz is 
the name of the terminal and the name that you pass nroff via the -T option 
(for example, nroff -Txyz). 



chname width output 



charset 
em 1 - 



hy 1 - 
VI- 

bu 1 +\bo 



FILES 



/ usr / lib / n term / tab. name 



terminal files 



SEE ALSO 



nroff(l). 
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NAME 

pic — troff preprocessor for drawing pictures 

SYNOPSIS 

pic [ -Tttyjype ] [ ~ ] [ file(s) ] 

DESCRIPTION 

pic is a troff(l) preprocessor for drawing simple figures on a typesetter. The 
basic objects are box, circle, ellipse, line, spline, arrow, arc and text. 

The optional argument -Tttyjype specifies device ttyjype; currently sup- 
ported devices are aps (Autologic APS-5) and ilO (Imagen Imprint-10), 
Default is —Taps. 

SEE ALSO 

grap(l), troff(l). 
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NAME 

ptx — make permuted index 

SYNOPSIS 

ptx [ opHonis) ] [ input [output] ] 

DESCRIPTION 

ptx generates the file output that can be processed with a text formatter (nroff 
or troff) to produce a permuted index of file input. Standard input (— ) and 
standard output are default. It has three phases: the first does the permuta- 
tion, generating one line for each keyword in an input line. The keyword is 
rotated to the front. The permuted file is then sorted. Finally, the sorted 
lines are rotated, so the keyword comes at the middle of each line, ptx output 
is in the following form: 

.XX ''before keyword" ^'kci/wonf ''after keyword" 

where .xx is assumed to be an nroff(l) or Iroff(l) macro provided by the user 
or provided by ptx(l). The — mptx macro package provides the .xx macro 
definition. The before keyword and after keyxoord fields incorporate as much of 
the line as will fit around the keyword when it is printed. The first field and 
last field, at least one of which is always the empty string, are wrapped- 
around to fit in the unused space at the opposite end of the line. 

The following option(s) can be applied: 

— f Fold upper- and lower-case letters for sorting, 

— t Prepare the output for the phototypesetter. 

— w n Use the next argument, h, as the length of the output line. 

The default line length is 72 characters for nroff and 100 for 

troff. 

— g n Use the next argument, n, as the number of characters that ptx 
will reserve in its calculations for each gap among the four 
parts of the line as finally printed. The default gap is 3. 

— o only 

Use as keywords any words given in the only file. 
— i ignore 

Do not use as keywords any words given the ignore file. If the 
— i and — o options are missing, use /usr/lib/eign as the ignore 
file. 
— b break 

Use the characters in the break file to separate words. Tab, 
new-line, and space characters are always used as break charac- 
ters. 

— r Take any leading non-blank characters of each input line to be 
a reference identifier (as to a page or chapter), separate from 
the text of the line. Attach that identifier as a 5th field on 
each output line. 
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FILES 

/bin/sort 

/usr/lib/eign 

/usr/lib/tmac/tmac.ptx 

SEE ALSO 

nroff(2), troff(l), mm(5), mptx(5). 

BUGS 

Line length counts do not account for overstriking or proportional spacing. 
Lines that contain tildes C) are botched because ptx uses that character inter- 
nally, ptx does not discard non-alphanumeric characters. 
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NAME 

subj ~ generate a list of subjects from a document 

SYNOPSIS 

subj file($) 

DESCRIPTION 

subj searches file(s) for subjects that might be appropriate in a subject-page 
index and prints the list of subjects on the standard output. The document 
should contain formatting commands (from nroff, troff, and mm among oth- 
ers) to make the best use of subj. 

SEE ALSO 

ndx(l), troff(l), mm(l), nroff(l). 

WARNINGS 

subj selects sequences of capitalized words as subjects except the first word in 
each sentence. Thus, if a sentence begins with a proper noun, the capitaliza- 
tion rule will not select this word as a subject. On the other hand, since each 
sentence is expected to begin on a newline, the first word of a sentence that 
begins in the middle of a line may be erroneously selected. 

The output of subj may not be appropriate for your needs and should be 
edited accordingly. 

BUGS 

subj also selects as subjects modifier-noun sequences from the abstract, head- 
ings, and topic sentences (the first sentence in each paragraph), and occasion- 
ally a word is incorrectly categorized as a noun or adjective. 
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NAME 

tbl - prepare tables for nroff or troff 

SYNOPSIS 

tbl [ -T X ] [ ~ ] [ file(s) ] [ - ] 

DESCRIPTION _ 

tbl is a preprocessor that prepares tables for ntoH(l) or troff(l). tbl assumes 
that lines between the .TS and .TE command lines describe tables, thus they 
are re-formatted; lines outside these command lines are copied to the standard 
output, (tbl does not alter the .TS and .TE command lines. 
Follow .TS with global options. The available global options are: 

center centers the table (default is left-adjust); 

expand makes the table as wide as the current line length; 

box encloses the table in a box; 

doublebox encloses the table in a double box; 

allbox encloses each item of the table in a box; 

tab (x) uses the character x instead of a tab to separate items 

in a line of input data. 

linesize in) sets line or rules (e.g., from box) in n-point type; 

End the global options, if any, with a semi-colon (;). 

After global options come lines describing the format of each line of the table. 
Each such format line describes one line of the table itself, except that the last 
format line (which you must end with a period) describes all remaining lines 
of the table. A single key letter describes each column of each line of the 
table. You may follow this key letter with specifiers that determine the font 
and point size of the corresponding item, that indicate where vertical bars are 
to appear between columns, and that determine column width, inter-column 
spacing, etc. The available key-letters are: 

c centers item within the column; 

r right-adjusts item within the column; 

1 left-adjusts item within the column; 

n numerically adjusts item in the column: units positions of 

numbers are aligned vertically; 
s spans previous item on the left into this column; 

a centers longest line in this column and then left-adjust all 

other lines in this column with respect to that centered line; 
^ spans down previous entry in this column; 

replaces this entry with a horizontal line; 
— replaces this entry with a double horizontal line. 
The characters B and I stand for the bold and italic fonts, respectively; the 
character | indicates a vertical line between columns. 

The format lines are followed by lines containing the actual data for the table, 
followed finally by .TE. Within such data lines, data items are normally 
separated by tab characters. 

If a data line consists of only _ or -, a single or double line, respectively, is 
drawn across the table at that point; if a single item in a data line consists of 
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oiily _ or then that item is replaced by a single or double line. Some 
printers do not have the vertical resolution to produce double lines. 

Full details of all these and other features of tbl are given in the tutorial and 
technical discussion cited below. 

The -TX option forces tbl to use only full vertical line motions, making the 
output more suitable for devices that cannot generate partial vertical line 
motions (for example, line printers). 

If you give no file(s) as arguments, or if you specify - as file(s), tbl reads the 
standard input so it may be used as a filter. When you use it with eqn(l) or 
neqn(l), put tbl first to minimize the volume of data passed through pipes. 
EXAMPLE 

If we let represent a tab (which should be typed as a genuine tab), then the 
input: 

•TS 

center box ; 
cB s 8 
cl I cl s 
I c c 
1 I n n • 

Household Population 

Town-^Households 
-^Number— *Size 

Bedminster-»789-*3.26 
Bernards Twp.-»3087-*3.74 
Bernardsville-^2018-*3.30 
Bound Brook-*3425— 3.04 
Bridgewater— 7897-^3.81 
Far Hills— 240— 3.19 
.TE 

yields: 



Household 


Population 




Town 


Households 


Number 


Size 


Bedminster 


789 


3.26 


Bernards Twp. 


3087 


3.74 


Bernardsville 


2018 


3.30 


Bound Brook 


3425 


3.04 


Bridgewater 


7897 


3.81 


Far Hills 


240 


3.19 



2 ttEFEBENCE MANUAL 



TBL(l) 



TBL(l) 



eqn(l), mm(l), inmt(l), mvt(l), neqn(l), nroff(l), tro£f(l). mm(5), and mv(5). 

The "tbl: Technical Dicussion." 

The Preprocessor tbl" in the User's Guide. 

BUGS 

See BUGS under nroff(l). 
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NAME 

tc - troff output interpreter 
SYNOPSIS 

tc [ -t ] [ -o list ] [ -a n ] [ -e ] [ file(s) ] 

DESCRIPTION Tu 
tc interprets its input (standard input default) as output from troft(l). Ihe 
standard output of tc is intended for a TEKTRONIX 4015 (a 4014 terminal with 
ASCII and APL character sets). The various typesetter sizes are mapped into 
the 4014's four sizes; the entire troff character set is drawn using the 4014's 
character generator, using overstruck combinations where necessary, produc- 
ing an altogether displeasing effect. Typical usage: 

troff troff j>ption(s) fiie(s) \ tc 
At the end of each page tc waits for a new-line (empty line) from the key- 
board before continuing on to the next page. In this wait state, the following 
commands are recognized: 
\cmd Send cmd to the shell, 
e inverts state of the screen erase 

— n skip backward n pages, 
aw sets the aspect ratio to n. 
? prints list of available options. 

The command line options are: 

-t does not wait between pages (for directing output into a file). 

-o list prints only the pages enumerated in list. The list consists of pages 
and page ranges (e.g., 5-17) separated by commas. The range w- goes 
from n to the end; the range -n goes from the beginning to and 
including page «. 

-a n sets the aspect ratio to n; default is 1.5. 

-e does not erase before each page. 
SEE ALSO 

4014(1), nroff(l), tplot(lG), and troff(l). 

BUGS 

Font distinctions are lost. 

It needs a -w option to wait for input to arrive. 
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NAME 

troff - text formatting and typesetting language 
SYNOPSIS 

troff [ option(s) 1 [ ~ ] [ fite(s) ] \ typesetter 

DESCRIPTION ^ ^ 

troff formats text In the named file for printing on a phototypesetter or com- 
parable device. 

If no file($) argument is present, the standard input is read. An argument con- 
sisting of a single minus (-) is taken to be a file name corresponding to the 
standard input. The options, which may appear in any order so long as they 
appear before the files, are 

-olist Print only pages whose page numbers appear in the comma- 
separated list of numbers and ranges. A range N-M means pages 
N through M; an initial -N means from the beginning to page N; 
and a final N- means from N to the end, (See BUGS below.) 

-nN Number first generated page N. 

-sN Generate output to make typesetter to stop every N pages. 

-mname Prepend the macro file /usr/lib/tmac/tmac.«ame to the input, 

file(s). 

-rflN Set register a (one character name) to N, 
-i Read standard input after the input files are exhausted, 

-q Invoke the simultaneous input-output mode of the .rd request. 

Print only messages generated by .tm requests. 
Send a printable ASCII approximation of the results to the standard 
output. 

Tttyjype output for typesetter or laser printer ttyjype. Supported 

devices are aps (Autologic APS-5 typesetter) ilO (Imagen 
ImprintJO). Alternatively, the environment variable 
"TYPESETTER" may be set. 

/usr/lib/tmac/tmac* pointers to standard macro files 
/usr/lib/macros/* standard macro files 
/usr/lib/font/dev*/* font width tables 
/usr/tmp/trtmp* temporary file 

SEE ALSO 

daps(l), dilO(l), eqn(l), grap(l), mmt(l), nroff(l), pic(l), tbl(l), tc(l); 
The "nroff/troff Technical Discussion" 
"The Formatter troff" in the User's Guide, 

The .tl request may not be used before the first break-producing request in 
the input to troff. 



— z 
—a 



FILES 
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troff believes in Eastern Standard Time; as a result, depending on the time of 
the year and on your local Hme zone, the date that trolf generates may be otf 
by one day from your idea of what the date is. 

When trotf is used with the -olist opHon inside a pipeline (e.g. with one or 
more of pic(l), eqn(l), and tbl(l)), it may cause a harmless ''broken pipe" 
diagnostic if the last page of the document is not specified in list 
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NAME 

troff - description of output language 
DESCRIPTION 

The device-independent troff outputs a pure ASCII description of a typeset 
document. The description specifies the typesetting device, the fonts, and the 
point sizes of characters to be used as well as the position of each character on 
the page. A list of all the legal commands follows. Most numbers are 
denoted as n and are ASCII strings. Strings inside of [ J are optional, troff 
may produce them, but they are not required for the specification of the 
language. The character \n has the standard meaning of "newline" character. 
Between commands white space has no meaning. White space characters are 
spaces and newlines. 

g„ The point size of the characters to be generated. 

I„ The font mounted in the specified position is to be used. 

The number ranges from to the highest font presently 
mounted. is a special position, invoked by troff, but 
not directly accessible to the troff user. Normally fonts 
are mounted starting at position 1. 

cx Generate the character x at the current location on the 

page; x is a single ASCII character. 

Cxyz Generate the special character xyz. The name of the 

character is delimited by white space. The name will be 
one of the special characters legal for the typesetting 
device as specified by the device specification found in 
the file DESC, This file resides in a directory specific for 
the typesetting device. (See font(5) and 
/usr/lib/font/dev*.) 

Change the horizonal position on the page to the 
number specified. The number is in basic units of 
motions as specified by DESC, This is an absolute "goto". 

li„ Add the number specified to the current horizontal posi- 

tion. This is a relative "goto". 

Vn Change the vertical position on the page to the number 

specified (down is positive). 

v„ Add the number specified to the current vertical posi- 

tion. 

This is a two-digit number followed by an ASCII charac- 
ter. The meaning is a combination of hnw followed by 
ex. The two digits nn are added to the current horizon- 
tal position and then the ASCII character, x, is produced. 
This is the most common form of character specification. 
^ a This command indicates that the end of a line has been 

reached. No action is required, though by convention 
the horizontal position is set to 0. troff will specify a 
resetting of the x,y coordinates on the page before 
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requesting that more characters be printed. The first 
number, b, is the amount of space before the line and 
the second number, a, the amount of space after the line. 
The second number is delimited by white space, 
w Aw appears between words of the input document. No 

acHon is required. It is included so that one device can 
be emulated more easily on another device. 

^gi*^ a new page. The new page number is included in 
this command. The vertical position on the paee should 
be set to 0. ^ 

^ — A line beginning with a pound sign is a comment. 

^ y Draw a line from the current location to y, 

''^^ Draw a circle of diameter d with the leftmost edge being 

at the current location (x, y). The current location after 
drawing the circle will be x+rf,y, the rightmost edge of 
the circle. 

De dx dy\n Draw an ellipse with the specified axes, dx is the axis in 

the X direction and dy is the axis in the y direction. The 
leftmost edge of the ellipse will be at the current loca- 
tion. After drawing the ellipse the current location will 
be x+dx,y. 

ba dhl dvl dh2 dv2\n Draw a counterclockwise arc from the current position 
to dhMdhl, dvl-^-dvl whose center is dhl, dvl from the 
current position. The current location after drawing the 
arc will be at its end. 

D'xyxy,..\n Draw a spline curve (wiggly line) between each of the 

x,y coordinate pairs starting at the current location. The 
final location will be the final x,y pair of the list. 

X qnitlVn Initialize the typesetting device. The actions required 

are dependent on the device. An init command will 
always occur before any output generation is attempted. 

X T device\n The name of the typesetter is device. This is the same as 

the argument to the -T option. The information about 
the typesetter will be found in the directory 
/u8r/!ib/font/dev(fei;ic^. 

X i(es] n h v\n The resolution of the typesetting device in increments 

per inch is n. Motion in the horizontal direction can 
take place in units of h basic increments. Motion in the 
vertical direction can take place in units of v basic incre- 
ments. For example, the APS-5 typesetter has a basic 
resolution of 723 increments per inch and can move in 
either direction in 723rds of an inch. Its specification is- 
X res 723 1 1 
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TROFF(5) 

X p(ause^n 
X s[top^n 

X t(railer]Vn 

X qont] n name\n 
X HJeight] n\n 

X S{lant] n\n 



TROFF(5) 

Pause. Cause the current page to finish but do not relin- 
quish the typesetter. 

Stop. Cause the current page to finish and then relinqu- 
ish the typesetter. Perform any shutdown and book- 
keeping procedures required. 

Generate a trailer. On some devices no operation is per- 
formed. 

Load the font name into position n. 
Set the character height to n points. This causes the 
letters to be elongated or shortened. It does not affect 
the width of a letter. Not all typesetters can do this. 
Set the slant to n degrees. Only some typesetters can do 
this and not all angles are supported. 
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Introduction 



If you have limited experience using the DOCUMENTER'S WORKBENCH 
Software, this reference handbook is designed for you. It shows various 
files before and after formatting and explains the role of each request or 
macro in the "input" file. 

You should not use this handbook to learn how to use DOCUMENTER'S 
WORKBENCH Software tools; the DOCUMENTER'S WORKBENCH Software User's 
Guide (310-004) is the authoritative primer. Annotated, concrete examples 
for nroff , mm, tbl, neqn/eqn, troff , and pic are provided here to jog your 
memory after you use the User's Guide. 

Two other documents are available for the more experienced 
DOCUMENTER'S WORKBENCH Software user. The DOCUMENTER'S WORK- 
BENCH Software Technical Discussion and Reference Manual (310-005) is the 
source for technical details, and the DOCUMENTER'S WORKBENCH Software 
Handbook (310-008) is a memory jogger for people with technical expertise. 



How to Read this Handbook 

1 . First, this handbook presents an input, or source, file in 
unformatted form (input). The source files presented here 
also appear wholly or partially in the "Sampler" of the Use/s 
Guide, and they are available for you to copy (see the Preface 
to the "Sampler"). 

2. Next, each macro or request in the input file is explained. 

3. This handbook next suggests where in the User's Guide or in 
the Technical Discussion and Reference Manual to find more 
information about the DOCUMENTER'S WORKBENCH 
Software components used in the example, 

4. Command lines for formatting the file are presented next. 
These command lines show you how to store the formatted 
output in a file and how to send the formatted output to a 
printer or, where appropriate, to a phototypesetter. 

5. Finally, this handbook shows the formatted file (input.out). 
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Introduction . . . 

This handbook observes the following rules: 
[] specifies an optional argument 

Italic text shows where you may substitute appropriate values 

Bold text shows where you must type exactly what is specified 

Check with your system administrator for locally available output dev- 
ices (printer or phototypesetter). 
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nroff 



input: 




.in +0.5i 
October 14. 1984 
.sp 2 
.nf 

John Smith 

Business Conpiter Systems, Inc. 
190 River Boulevard 
Durham, NC 27707 
.sp 2 

Dear Mr. Skciith: 

.sp 2 

.fi 

I would like to be considered for the position of Document Production Coordinator 
with Business Conputer Systecns, Inc. 

I have a B.A. in English and have fimshed course work for a Masters in English. 
CXirrently, I am assisting Steve Foley, Production Editor with Techno-Publishing 
in Jonesville. 

My duties consist of proofreading documents and coordinating graphics production, 
.sp 

While I enjoy ray position here, I know I am ready for more challenging work and 
greater responsibility. 

Our shop uses a ccniputer running UNIX System V. 

I am confident in ny potential for growth with the Technical Writing Staff 
at Business Ccniputer Systems. 

I have enclosed ny resume and tsao letters of reccnniendatian. 

Please feel free to contact ny present suqpervisor with aiQr questions ycu may have. 
I am available for an interview at any time, and I look forward to hearing from 
you. 

.sp 2 

.nf 

Sincerely yours, 
.sp 5 



John Jones 

41 Stanford Drive 

Bridgewater, KJ 08807 
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nroff 



Explanation 



•in +0.5i 



indents all text one-half inch from the left margin 
places two lines of space between the lines it separates 
turns off line filling 
turns on line filling 



•sp 2 



.nf 



.sp 



5 



places five lines of space between the lines of text it 
separates 



"The Formatter nroff: a Tutoriar in the User's Guide teaches you how to 
control attributes of your formatted document, including the margins, 
indentation, hyphenation, number of characters per line, and lines per 
page. It also discusses number registers and strings. The chapter titled 
"nroff /troff Technical Discussion" in the Technical Discussion and Reference 
Manual comprehensively discusses nroff and provides the nroff (1) manual 
page. 
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nroff 



input.out 



October 14, 1984 



John Smith 

Business Computer Systems, Inc, 
190 River Boulevard 
Durham, NC 27707 



Dear Mr. Smith: 



I would like to be considered for the position of Document 
Production Coordinator with Business Computer Systems, Inc. 
I have a B.A. in English and have finished course work for a 
Masters in English. Currently, I am assisting Steve Foley, 
Production Editor with Techno-Publishing in Jonesville. My 
duties consist of proofreading docijments and coordinating 
graphics production. 

While I enjoy my position here, I know I am ready for more 
challenging work and greater responsibility. Our shop uses 
a computer running UNIX System V. I am confident in my 
potential for growth with the Technical Writing Staff at 
Business Computer Systems. I have enclosed my resume and 
two letters of recommendation. Please feel free to contact 
ray present supervisor with any questions you may have. I am 
available for an interview at any time, and I look forward 
to hearing from you. 

Sincerely yours. 



John Jones 

41 Stanford Drive 

Bridgewater, NJ 08807 



Enclosures: 3 
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mm 

input: 



.TL 

Vtork Progress Report ~ Seoand Quarter 1984 

.AF "Busijiess Cat53uter Systens, Inc." 

.AU "W. Williains" VW XF 665414 5398 7-123 baileylwww 

.MT 

.HU "Writing Assignments" 
.P 

I started work vdth the Technical Writing Staff on April 16. 

Myr writing assignments are: 

.BL 

.LI 

Dcxannentatiai for the BCS Pcatran ccapiler 

.DL 

.LI 

I collected materials relevant to inplementing progranniing languages 
cn the UNIX* 
.FS # 

Tradanark of AOST 
.EE 

system. 

.LE 

.LI 

Documentation for the Distrihuted Transaction Processing System (DTPS) 2 

.DL 

.LI 

I reviewed DTPS requirements, outstanding oonplaints about ETEPS, and users' 

suggestions for iirproving DTPS docunentaticn. 

.LE 

.LE 

.HU "Other Activities" 
.P 

Oi June 16, I went to a conference, "Writing About Conpiters," at Acme State 
College. 
S6 
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mm 



Explanation 

.TL formats the lines that follow it (until the next macro) as 

the title of a formal memorandum 

.AF formats the name of the firm, "Business Computer Sys- 
tems, Inc." 

.AU formats information about the author 

.MT chooses a formal memorandum type 

.HU formats an unnumbered heading 

,P begins a new paragraph 

.BL initializes a bullet list 

XI specifies that the text that follows is a list item 

.DL initializes a dash list 

JS signals the beginning of footnote text 

JE signals the end of footnote text 

.LE signals the end of a list 

.SG prints the signature line 

1 "The mm Macro Package: a Tutorial" in the User's Guide teaches you how to 

NCTO format documents with mm using its defaults and, for some macros, teaches 
_J you how to refine the way they work. The chapter titled "mm Technical 
i"^ Discussion" in the Technical Discussion arid Reference Manual comprehensively 
discusses this package. It also provides manual pages for the mm and mmt 
commands (mm(l), mmt(l)) and the mm macro package (mm(5)). 
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mm 



Command Lines 

mm [options] input > input.out 

or 

mm [options] input | printer 
or 

mmt [options] input | phototypesetter 
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mm 



input.out 



Business Computer Systems, Inc. 



subject: Work Progress Report -- 
Second Quarter 1984 



date: December 4, 1985 



from: 



Williams 
XF 665414 
7-123 X5398 
bailey ! www 



Writing Assignments 

I started work with the Technical Writing Staff on April 16. 
My writing assignments are: 

o Documentation for the BCS Fortran compiler 

- I collected materials relevant to implementing 
programming languages on the UNIX* system. 

^ Documentation for the Distributed Transaction 
Processing System (DTPS) 2.0 

- I reviewed DTPS requirements, outstanding 
complaints about DTPS, and users* suggestions for 
improving DTPS documentation. 

Other Activities 

On June 16, I went to a conference, "Writing About 
Computers," at Acme State College. 



W. Williams 



* Trademark of AT&T 
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tbl 



<TAB> means to press the TAB key. 
input: 



.TS 

box, center; 
c c c 
111. 

La]igiiage<TAB>Autlx]irs<TAB>Priinary Use 
.sp 

APL<M>IBM<T*B>Mathecatics, Applications 
Basic<TAB>DartxQouth<ua>Teaching, i^splications 
C<TAB>BrL<TOB>SystenB, Applications 
CX}6QL<iMB>Msmy<nffi>6usiness implications 
Fartran<Tffi>Mary<MB>Scientif ic Applications 
LiSP<TAB>M.I.T.<TAB>Artificial Intelligence 
Pdscal<i»B>Stan£ord<TAB>Teaching, Systecse 
FL/1 <a»B>IEM<TAB>AFplications 
SN0QQL4<isAB>A!rSLT<nm>Ai:plicatiQns 
.TB 



Explanation 

•TS signals the beginning of a table 

box, center; tells tbl to center the output and enclose the entire table 
in a box. The comma between the two words delimits 
each instruction. The character ends global options, 
telling tbl that what follows is the format section. 
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tbl 



c c c 



1 1 1. makes up the format section, and tells tbl that there are 

three columns in the table. In the first row, each column 
should be centered, and in the second and following 
rows, each column should be flush left. The character 
ends the format section, telling tbl that what follows is 
text to be put in the table. 

,sp places one line of space between the lines of text that it 

separates 

draws a line the width of the table between the text lines 
that it separates 

.TE signals the end of a table 



NOflE 



"The Preprocessor tbl: a Tutorial" in the Use/s Guide teaches you how to 
prepare tables of varying degrees of complexity. The chapter "tbl Technical 
Discussion" in the Technical Discussion and Reference Manual comprehensively 
discusses this preprocessor. It also provides a manual page for the tbl(l) 
command. 



Command Lines 

tbl -TX input | nroff -mm -Tip [options] \ col > input.out 

or 

tbl -TX input | nroff -mm -Tip [options] \ col | printer 
or 

mm -t -Tip [options] input > input.out 

or 

mm -t -Tip [options] input | printer 
or 

tbl input Itroff -mm -Tttyjype [options]\phototypesetter 
or 

mmt -t -Tttyjype [options] input | phototypesetter 
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inputout 



Language Authors 



Prxmary Use 



FAPL 
I Basic 
IC 

I COBOL 
I Fortran 
I LISP 
(Pascal 
I PL/1 
I SN0B0L4 
I 



IBM 

Dartmouth 

BTL 

Many 

Many 

M.I.T. 

Stanford 

IBM 

AT&T 



Mathematics, Applications 
Teaching, Applications 
Systems, Applications 
Business Applications 
Scientific Applications 
Artificial Intelligence 
Teaching, Systems 
Applications 
Applications 
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neqn/eqn 

neqn prepares equations for the nroff formatter, eqn prepares them 
for troff. 

input: 




.p 

Bje mean is the arithmetic average for a set of scores. 

The fczRuIa for ccnpiting a mean (M) is 

.sp 2 

.DS 

.BQ 

M {sum fron {i-=-1> to n {x sub i> } over n 




Explanation 

.? (an mm macro) begins a new paragraph 

.sp 2 (an nroff request) places two lines of space between the 

text it separates 

.DS (an mm macro) starts a static display. When you put an 

equation in a document formatted with mm macros, you 
must put it inside a static display (shown here) or a float- 
ing display. 

.EQ tells neqn/eqn that what follows, here 

M {sum fron {i-=-1} to n {x sub i} } over n 

is a displayed equation to be formatted, sum, from, to, 
sub, and over are eqn instructions. The character " 
translates into a space. 
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•EN ends the displayed equation 

•DE ends the static display 



The chapter titled The Preprocessor neqn/eqn: a Tutorial^ in the Use/s 
Guide teaches you about this preprocessor. The chapter "eqn Technical Dis- 
cussion" in the Technical Discussion and Reference Manual comprehensively 
discusses its use. The Technical Discussion and Reference Manual also provides 
manual pages for neqn(l) and eqn(l). 



Command Lines 

neqn input | nroff [options] > input.out 
or 

neqn input | nroff [options] \ printer 
or 

eqn input | troff [options] > inputout 
or 

eqn input | troff [options] \phototypesetter 



input.out: 



The mean is the arithmetic average for a set of scores. The formula for computing a mean (M) 



n 
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troff 



input: 




.sp 4 
.ps 14 
.vs 16 
.Is 2 

However sophisticated your printer is, \fltro£f\£R can prctoably handle your font 
oontzol. 

By placing .ft on a line fcy itself before the line of text you want to change 

cr \f before the word or words yaa want to change, you can modify your typography. 

.ft I 

Ihis is a line of italic made with .ft X (italic). 

.br 

.ft B 

If yaa prefer a heavier eojiiasis, use bold ronan type made with .ft B (bold) . 

.br 

.ft H 

Rar the clean appearance of a sans serif type, use .ft H (Helvetica). 

.br 

.ft R 

Banan is the most popular, of course. 
.P 

Hie \f allows for a finer level of ccntrol: 

The individual \fIitalic\fR, \fBbold\fR, or \fHHelvetica\fR word can be done 

in-line. 

.P 

All printers were not made equal, so consult your systems manager to find what 
is available, 
.ps 10 
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troff 



Explanation 

turns no-space mode off 

•sp 4 places four lines of space between the lines it separates 

.ps 14 sets the point size to 14 (ignored by nroff) 

.vs 16 sets vertical spacing between output lines to 16 points 

••^ ^ sets line-spacing to 2, that is, one line of space is placed 

between each pair of output lines. 

(an mm macro) begins a new paragraph 

I changes the font to italics 

•br forces a line break 

•f* B changes the font to bold 

•'^ H changes the font to Helvetica 

•ft R changes the font to roman 

changes font in the middle of a line, e.g., \f 1 changes 
font to roman wherever it appears in the text 

•ps 10 changes point size to 10 

•vs 12 changes vertical spacing to 12 

••^ ^ Sets line spacing to 1, which is the default 



NOTE 



The tutorial titled The Formatter troff: a Tutorial" in the User's Guide 
teaches you about local motion, font and point size changes, basic graphics 
as well as the programming capabilities of troff. The chapter "nroff/troff ' 
Technical Discussion" in the Technical Discussion and Reference Manual 
comprehensively discusses troff. It also provides a manual page for troff(l) 
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troff 



Command Lines 

troff -mm [options] input | phototypesetter 
or 

mmt [options] input | phototypesetter 
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input.out: 



However sophisticated your printer is, troff can probably handle your 
font control. By placing .ft on a line by itself before the line of text 
you want to change or \f before the word or words you want to change, 
you can modify your typography. This is a line of italic made with .ft 
I (italic). 

If you prefer a heavier emphasis, use bold roman type made with .ft B 
(bold). 

For the clean appearance of a sans serif type, use .ft H (Helvetica). 
Roman is the most popular, of course. 

The \f allows for a finer level of control: The individual italic, bold, or 
Helvetica word can be done in-line. 

All printers were not created equal, so consult your systems manager to 
find what is available. 
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pic 

input: 




Hie f earns that \fIpic\fR provides are 
.sp 2 
.in +1i 
.PS 

circle "circle"; move; box "box"; move; arrow "arrow" above 

.PE 

.sp 2 

.PS 

ellipse "ellipse"; move; line "linS" above; move; arc "arc" 
.PE 

.in -1i 
.P 

NflpicXfR's language is intuitive, so na3dng ycur cwn farms is not hard. 
For instance, 

you can talk to \fIpic\£R as you would to scmeone drawing shapes with a pencil: 
.PS 

.in +0.3i 

ellipse; line ric^t; arc; arc; arc; line down 1i; circle; arrow ri^t; box dashed 

line right; line dotted ric^t; arc; arrow dashed; box "Ihere." 

.FE 

•in -0.3i 

Since you can store these instructions in special coosnands, ycu are able to 
ooKipile a personal library of shapes, naming them vAiatever you like: 
.DS I 

iiqxit^output 
nolecular^struct 
solar system 
.DE 

And these you can even tailor later to suit your particular needs in any document. 

For instance, the following exanple might be used to demonstrate the concept of 

processing: 

.in +0.75i 

,sp 1 

.PS 

box "input"; arrow; ellipse "processing"; arrow; box "output" 
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pic 



Explanation 

(an mm macro) begins a new paragraph 

(a troff request) puts two lines of space between the 
lines of text it separates 

indents one inch all text that follows. Other instances of 
.in in this example indent text various distances. 

tells pic that what follows should be interpreted as 
instructions to draw a picture. In this example, the basic 
shapes that pic offers are drawn, labeled by their names; 
for example, circle "circle" instructs pic to put a circle 
around the word "circle." circle, itove, box, arrow, 
and above are keywords for pic. More elaborate pictures 
are drawn after these shapes are labeled. 

ends a picture for pic 

(an mm macro) starts an indented static display 
(an mm macro) ends the static display 



"The Preprocessor pic: a Tutoriar in the User's Guide teaches you how to 
draw with pic. The Technical Discussion and Reference Manual provides a 
manual page for the pic(l) command. 



Command Lines 

pic input I troff -mm [options] \ phototypesetter 
or 

mmt -p [options] input \ phototypesetter 



.P 

•sp 2 
.in +li 
.PS 



.PE 

.DSI 

.DE 



20 HANDBOOK FOR NEW USERS 



pic 



inputout: 



The forms that pic provides are 




box 



arrow 




line 



p/c's language is intuitive, so making your own forms is not hard. For instance, you can talk to pic 
as you would to someone drawing shapes with a pencil: 






There. 



^ — — — — — — -J 

Since you can store these instructions in special commands, you are able to compile a personal 
library of shapes, naming them whatever you like: 

input_output 

molecular_struct 

solar_system 

And these you can even tailor later to suit your particular needs in any document. For instance, the 
following example might be used to demonstrate the concept of processing: 
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NOTES 



NOTES 



NOTES 



NOTES 
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